Slider docs are unclear, SliderGrid is unnecessary

[KronosTheLate]

The documentation for Slider states the following:

Labelled sliders and grids

The functions labelslider! and labelslidergrid! are deprecated, use SliderGrid instead.

This is unclear to me - SliderGrid has replaced labelslider!? Does that mean that one should make a SliderGrid for a single labeled slider?

If we jump to the link to SliderGrid, we meet the following:

SliderGrid

SliderGrid <: Block

A grid of horizontal Sliders, where each slider has one name label on the left, and a value label on the right.

Each NamedTuple you pass specifies one Slider. You always have to pass range and label, and optionally a format for the value label. > Beyond that, you can set any keyword that Slider takes, such as startvalue.

If the intention is for users to make a SliderGrid when they want a single labeled slider, the docs for SliderGrid should state something more to the effect of "Make one or more labeled sliders". As it is, I am uncertain how I should make a single labled slider in the intended way.

Furthermore, we see the docstring for SliderGrid start with "A grid of horizontal Sliders". Does that mean that it is impossible to create a vertical SliderGrid? But if I should use SliderGrid to create a single labeled slider, as indicated by the documentation stating that one should use SliderGrid instead of lableslider!, how do I create a single labled vertical slider? It feels like it has not actually replaced something like labelslider! (as the docs seems to suggest), but rather partially replaced it, and that the docs should be more clear on that the replacement is partial. Ideally, it would not feel like a partial replacement.

Fortunatly, the docs for Slider clearly state that "You can create a label using a Label object, for example". So I know I can do it manually, by @lifting a label containing the variable name I want and value of the slider. But that seems a little manual, considering that there was a labelslider! in the past, and the reference from it to SliderGrid seems to indicate that there are more automatic ways to make a labeled slider.

Before fixing this - Why do we need SliderGrid?

Before discussing how the docs should be, I want to know - why do we need SliderGrid? It seems to me like Slider can do everything we want - be vertical and slide. It is just missing the label and format kwargs, which could be implemented just like for a single slider in a SliderGrid. Why use different types for wanting one (Slider) vs many (SliderGrid), instead of just creating many directly? I imagine usage would look like

s1 = Slider(fig[2, 1], label = "Amplitude", range = 0:0.1:10, startvalue = 5)
s2 = Slider(fig[3, 1], label = "Frequency", range = 0:0.5:50, format = "{:.1f}Hz", startvalue = 10)
s3 = Slider(fig[4, 1], label = "Phase", range = 0:0.01:2pi,
        format = x -> string(round(x/pi, digits = 2), "π"))

# or as a vector of sliders:
sliders = [
    Slider(fig[2, 1], label = "Amplitude", range = 0:0.1:10, startvalue = 5),
    Slider(fig[3, 1], label = "Frequency", range = 0:0.5:50, format = "{:.1f}Hz", startvalue = 10),
    Slider(fig[4, 1], label = "Phase", range = 0:0.01:2pi,
        format = x -> string(round(x/pi, digits = 2), "π"))
]

Compare this to the current syntax for making a SliderGrid, and I do not see the drawback. It is more or less identical:

sg = SliderGrid(fig[1, 1],
    (label = "Amplitude", range = 0:0.1:10, startvalue = 5),
    (label = "Frequency", range = 0:0.5:50, format = "{:.1f}Hz", startvalue = 10),
    (label = "Phase", range = 0:0.01:2pi,
        format = x -> string(round(x/pi, digits = 2), "π"))
)

It seems just as easy to make many Sliders as a SliderGrid. Why introduce the extra type?

Furthermore, I find the syntax to access the values of a SliderGrid quite horrendus:

on(sg.sliders[2].value) do val
    # do something with `val`
end

This would, when just composing Sliders, become

# Version 1, binding to s1, s2, s3
on(s2.value) do val
    # do something with `val`
end

# Version 1, binding to sliders
on(sliders[2].value) do val
    # do something with `val`
end

[jkrumbiegel]

When you have multiple sliders in a grid, you want all the value labels to be formatted to take as little space as possible while not jittering the layout back and forth when updating. That's the point of having SliderGrid, that it does that work for you. It's not a simple function anymore to make it easier to move / delete the thing, instead of having a loose bag of objects.

[ffreyer]

Can this be closed?

[KronosTheLate]

I just revisited the docs quickly on my phone, and I do not see any of the issues raised having been dealt with. The most pressing one is spesifically:
Is the best way to create a single labeled slider by using a slidergrid? If yes, then (a) the name is misleading, and (b) the docs do not correct the impression made by the name.

[jkrumbiegel]

It's not the best way, it just deals with the text jitter issue relatively intelligently. And this makes most sense in a grid.

[KronosTheLate]

So the easiest wat to make a single labelled slider is using SliderGrid? If yes, It makes more sense to me to have a LabeledSlider of which one can create multiple, as opposed to making a grid and populating it with a single instance. It is just more natural to my mind to go from one to many, instead of starting with many and going to one.

I guess my point is just that it feels weird to use SliderGrid to make a single slider, and that a more natural plularization of a LabeledSlider (e.g. an array of LabeledSliders) feels like both a more discoverable and natural way to structure things. Functionally there is of course little difference.

[jkrumbiegel]

LabeledSlider of which one can create multiple

No that wouldn't work for what it does, the grid determines the largest label and uses that for the whole column. If you made multiple single LabeledSliders then they'd all have different label lengths and would look wonky when stacked.

[KronosTheLate]

Okay that makes sense.

I am not sure what a good solution looks like here. If you can not see it either (or still do not think this is a problem), then this can be closed for me.

[jkrumbiegel]

If your confusion comes from SliderGrid being suitable also for a single labeled slider, we could just add that to the docstring

[KronosTheLate]

That would not help the "naturalness" of the naming, but that seems tricky and is also less important. It WOULD remove the uncertainty a user might face, which is the main issue IMO. So yes, I would be more than happy just to have it mentioned in the docstring. Perhaps something to the effect of "constructing a SliderGrid is the easiest way to create one or more labelled sliders."

[japhir]

I also ran into this confusion today. It says the older syntax is deprecated but the SliderGrid docs weren't very clear on just creating a single labelled slider.

Maybe below should be a separate issue, but I'm here now anyway ;-):
I couldn't figure out how to make the single SliderGrid slider vertical, while with the single Slider you can put horizontal = false. For the SliderGrid, if I put horizontal = false in the tuple of slider info, the labels and names stay at the left/right of the slider in the SliderGrid, with a tiny tiny vertical slider ;-).

Perhaps the docs could show a simpler example with one labelled slider first, then also show vertical versions (if possible?)