Package swingtree

Class UIForSlider<S extends JSlider,N extends Number>

java.lang.Object
swingtree.UIForAnything<UIForSlider<S,N>,S,JComponent>
swingtree.UIForAnySwing<UIForSlider<S,N>,S>
swingtree.UIForSlider<S,N>
Type Parameters:
S - The type of JSlider that this UIForSlider is configuring.
N - The type of the numbers the slider works with.
public final class UIForSlider<S extends JSlider,N extends Number> extends UIForAnySwing<UIForSlider<S,N>,S>
A SwingTree builder node designed for configuring JSlider instances.

Please take a look at the living swing-tree documentation where you can browse a large collection of examples demonstrating how to use the API of this class.

A slider in SwingTree works with numbers of the type N, which is Integer unless you created the slider through one of the factory methods taking properties of another number type, like UIFactoryMethods.slider(UI.Axis, Number, Number, Var) with a Var<Double>. The minimum, the maximum, the value and the tick marks of the slider are all expressed in that type, even though a plain JSlider only knows whole numbers.

On a slider for whole numbers, a minimum or maximum set directly through JSlider.setMinimum(int) or JSlider.setMaximum(int) becomes the range of the slider, and its tick marks and labels are laid out again for that range. On a slider for Float or Double numbers, the whole numbers of the JSlider are an internal detail, so such a call is undone right away.

  • Method Details

    • _state

      protected swingtree.BuilderState<S> _state()
      Description copied from class: UIForAnything
      Returns the state of the builder, which is a container for the wrapped component as well as it's type and current EventProcessor.
      Specified by:
      _state in class UIForAnything<UIForSlider<S extends JSlider,N extends Number>,S extends JSlider,JComponent>
      Returns:
      The state of the builder.

    • _newBuilderWithState

      protected UIForSlider<S,N> _newBuilderWithState(swingtree.BuilderState<S> newState)
      Description copied from class: UIForAnything
      An internal wither method which creates a new builder instance with the provided BuilderState stored inside it.
      Specified by:
      _newBuilderWithState in class UIForAnything<UIForSlider<S extends JSlider,N extends Number>,S extends JSlider,JComponent>
      Parameters:
      newState - The new state which should be stored inside the new builder instance.
      Returns:
      A new builder instance with the provided state stored inside it.

    • withOrientation

      public final UIForSlider<S,N> withOrientation(UI.Axis axis)
      Sets the orientation of the slider.
      Parameters:
      axis - The orientation of the slider.
      Returns:
      This builder node.

    • withOrientation

      public final UIForSlider<S,N> withOrientation(sprouts.Val<UI.Axis> axis)
      Dynamically sets the orientation of the slider.
      Parameters:
      axis - The orientation of the slider.
      Returns:
      This builder node.

    • onChange

      public final UIForSlider<S,N> onChange(sprouts.Action<ComponentDelegate<JSlider,ChangeEvent>> action)
      Adds an Action which is called when the user changes the state of the slider, for example by moving its knob, or by pressing or releasing the mouse button on it. Changes which your application makes through the properties or values given to this builder do not call the action.

      Every change calls each action once, in the order in which the actions were added. When the knob snaps to a tick mark (see SliderTicks.withSnapToTicks(boolean)), the actions are called after the knob has snapped, so they read the number at that tick mark.

      Parameters:
      action - The Action that will be called through the underlying change event.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if action is null.

    • withMin

      public final UIForSlider<S,N> withMin(N min)
      Sets the minimum value of the slider, which is the number at the start of its track.
      Parameters:
      min - The minimum value of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if min is null.

    • withMin

      public final UIForSlider<S,N> withMin(sprouts.Val<N> min)
      Binds the supplied Val property to the minimum value of the slider, so that when the value of the property changes, the minimum of the slider, and with it the position of the knob and of the tick marks, is updated accordingly. When the user moves the knob, the value written back by the slider is never smaller than the item of this property.
      Parameters:
      min - The property holding the minimum value of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if min is null or allows null items.

    • withMax

      public final UIForSlider<S,N> withMax(N max)
      Sets the maximum value of the slider, which is the number at the end of its track.
      Parameters:
      max - The maximum value of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if max is null.

    • withMax

      public final UIForSlider<S,N> withMax(sprouts.Val<N> max)
      Binds the supplied Val property to the maximum value of the slider, so that when the value of the property changes, the maximum of the slider, and with it the position of the knob and of the tick marks, is updated accordingly. When the user moves the knob, the value written back by the slider is never larger than the item of this property.
      Parameters:
      max - The property holding the maximum value of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if max is null or allows null items.

    • withValue

      public final UIForSlider<S,N> withValue(N value)
      Sets the current value of the slider, which places the knob at that number. A number outside the range of the slider places the knob at the nearest end of the track.
      Parameters:
      value - The current value of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if value is null.

    • withValue

      public final UIForSlider<S,N> withValue(sprouts.Val<N> value)
      Binds the supplied Val property to the value of the slider, which causes the knob of the slider to move when the value of the property changes. But note that the supplied property is a read only, so when the user moves the knob, the property will not be updated. Use withValue(Var) if you want to bind a property bidirectionally.

      While the user holds the knob with the mouse, changes of the property do not move it.

      Parameters:
      value - A property used to dynamically update the value of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if value is null or allows null items.

    • withValue

      public final UIForSlider<S,N> withValue(sprouts.Var<N> value)
      Use this to bind the supplied Var property to the value of the slider. When the user moves the knob, the Var is updated, and when the item of the Var is changed as part of the application logic, the knob moves accordingly.

      The number written into the property is of the property's own type, and it is the number at the position of the knob, or, if the knob snaps to tick marks (see SliderTicks.withSnapToTicks(boolean)), the number at the tick mark it snaps to. A click on the knob which does not move it writes nothing new, so the property keeps exactly the number your application set.

      While the user holds the knob with the mouse, changes of the property do not move it, and when the user lets go, the number under the knob is written into the property.

      Parameters:
      value - A property holding the value of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if value is null or allows null items.

    • withMajorTickSpacing

      public final UIForSlider<S,N> withMajorTickSpacing(N spacing)
      Sets how far apart the major tick marks of the slider are, in the numbers of the slider. The major tick marks count from the minimum of the slider, so a spacing of 25 on a slider running from 0 to 100 puts a major tick mark at 0, 25, 50, 75 and 100. A spacing of zero or less removes the major tick marks.

      Like JSlider.setMajorTickSpacing(int), this method only sets where the major tick marks are. The slider draws them once JSlider.setPaintTicks(boolean) was called with true, for example through peek( s -> s.setPaintTicks(true) ). Unlike JSlider.setMajorTickSpacing(int), the spacing is a number of the slider's own type, so a slider for a Double property can have a major tick mark every 0.25.

      To describe tick marks, labels and snapping together, use withTicks(SliderTicks) instead. A slider which has been given a SliderTicks value takes its tick marks from that value and ignores the spacing given to this method, no matter in which order the two methods are called.

      Parameters:
      spacing - The distance between two neighbouring major tick marks, in the numbers of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if spacing is null.

    • withMajorTickSpacing

      public final UIForSlider<S,N> withMajorTickSpacing(sprouts.Val<N> spacing)
      Binds the supplied Val property to the spacing of the major tick marks of the slider, so that the major tick marks move whenever the item of the property changes. The spacing is a number of the slider's own type, and the major tick marks count from the minimum of the slider, so a spacing of 25 on a slider running from 0 to 100 puts a major tick mark at 0, 25, 50, 75 and 100. A spacing of zero or less removes the major tick marks.

      Like JSlider.setMajorTickSpacing(int), the property only decides where the major tick marks are. The slider draws them once JSlider.setPaintTicks(boolean) was called with true. A slider which has been given a SliderTicks value through withTicks(SliderTicks) or withTicks(Val) takes its tick marks from that value and ignores this property.

      Parameters:
      spacing - A property holding the distance between two neighbouring major tick marks, in the numbers of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if spacing is null or allows null items.

    • withMinorTickSpacing

      public final UIForSlider<S,N> withMinorTickSpacing(N spacing)
      Sets how far apart the minor tick marks of the slider are, in the numbers of the slider. The minor tick marks count from the minimum of the slider, so a spacing of 5 on a slider running from 0 to 100 puts a minor tick mark at 0, 5, 10 and so on up to 100. A spacing of zero or less removes the minor tick marks.

      Like JSlider.setMinorTickSpacing(int), this method only sets where the minor tick marks are. The slider draws them once JSlider.setPaintTicks(boolean) was called with true, for example through peek( s -> s.setPaintTicks(true) ). Unlike JSlider.setMinorTickSpacing(int), the spacing is a number of the slider's own type, so a slider for a Double property can have a minor tick mark every 0.05.

      The minor tick marks do not depend on the major tick marks. With a major spacing of 25 and a minor spacing of 10, the minor tick marks sit at 0, 10, 20, 30 and 40, while the major tick marks sit at 0, 25 and 50, so the minor tick marks do not divide the gaps between the major ones evenly. SliderTicks.withMinorTicksBetween(int) counts the minor tick marks between two major tick marks instead, which always divides the gaps evenly. A slider which has been given a SliderTicks value through withTicks(SliderTicks) takes its tick marks from that value and ignores the spacing given to this method, no matter in which order the two methods are called.

      Parameters:
      spacing - The distance between two neighbouring minor tick marks, in the numbers of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if spacing is null.

    • withMinorTickSpacing

      public final UIForSlider<S,N> withMinorTickSpacing(sprouts.Val<N> spacing)
      Binds the supplied Val property to the spacing of the minor tick marks of the slider, so that the minor tick marks move whenever the item of the property changes. The spacing is a number of the slider's own type, and the minor tick marks count from the minimum of the slider, so a spacing of 5 on a slider running from 0 to 100 puts a minor tick mark at 0, 5, 10 and so on up to 100. A spacing of zero or less removes the minor tick marks.

      Like JSlider.setMinorTickSpacing(int), the property only decides where the minor tick marks are. The slider draws them once JSlider.setPaintTicks(boolean) was called with true. A slider which has been given a SliderTicks value through withTicks(SliderTicks) or withTicks(Val) takes its tick marks from that value and ignores this property.

      Parameters:
      spacing - A property holding the distance between two neighbouring minor tick marks, in the numbers of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if spacing is null or allows null items.

    • withTicks

      public final UIForSlider<S,N> withTicks(SliderTicks<N> ticks)
      Configures the tick marks and labels along the slider through the supplied SliderTicks value, which describes where the major and minor tick marks are, whether they are drawn, whether the knob snaps to them and which labels are shown: 
      
  UI.slider(UI.Axis.HORIZONTAL, 0, 100, volume)
  .withTicks(
      SliderTicks.of(Integer.class)
      .withMajorSpacing(25)
      .withMinorTicksBetween(4)
      .withLabelsAtMajorTicks( v -> v + "%" )
  )
      The spacings and label positions are numbers of the slider's own type, so a slider for a Double property is configured with a SliderTicks<Double>. Whenever the minimum or maximum of the slider changes, the tick marks and labels are laid out again for the new range.
      Parameters:
      ticks - The tick marks and labels of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if ticks is null.

    • withTicks

      public final UIForSlider<S,N> withTicks(sprouts.Val<SliderTicks<N>> ticks)
      Binds the tick marks and labels along the slider to the supplied property holding a SliderTicks value, so that the slider shows the tick marks and labels of the property's current item, and follows every change of it.

      The property may live in your view model, or be derived from view model state right in the view, like this slider which shows its labels only while a flag says so: 

      
  SliderTicks<Integer> plain    = SliderTicks.of(Integer.class).withMajorSpacing(25);
  SliderTicks<Integer> labelled = plain.withLabelsAtMajorTicks();

  UI.slider(UI.Axis.HORIZONTAL, 0, 100, volume)
  .withTicks( showLabels.viewAs(SliderTicks.classTyped(Integer.class), show -> show ? labelled : plain) )
      Under the EventProcessor.DECOUPLED event processor the new SliderTicks reaches the slider as part of the property's change event, in the same order as every other change of the slider's properties.
      Parameters:
      ticks - A property holding the tick marks and labels of the slider.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if ticks is null or allows null items.