Package com.bric.multislider

Class MultiThumbSlider<T>

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
com.bric.multislider.MultiThumbSlider<T>
Type Parameters:
T - the type of data each float maps to. For example: in the GradientSlider this value is a Color. Sometimes this property may be unnecessary. If this slider is only meant to store the relative position of thumbs, then you may set this to a trivial stub-like object like a String or Character.
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable
public class MultiThumbSlider<T> extends JComponent
This JComponent resembles a JSlider, except there are at least two thumbs. A JSlider is designed to modify one number within a certain range of values. By contrast a MultiThumbSlider actually modifies a table of data. Each thumb in a MultiThumbSlider should be thought of as a key, and it maps to an abstract value. In the case of the GradientSlider: each value is a java.awt.Color. Other subclasses could come along that map to other abstract objects. (For example, a VolumeSlider might map each thumb to a specific volume level. This type of widget would let the user control fading in/out of an audio track.)

The slider graphically represents the domain from zero to one, so each thumb is always positioned within that domain. If the user drags a thumb outside this domain: that thumb disappears.

There is always a selected thumb in each slider when this slider has the keyboard focus. The user can press the tab key (or shift-tab) to transfer focus to different thumbs. Also the arrow keys can be used to control the selected thumb.

The user can click and drag any thumb to a new location. If a thumb is dragged so it is less than zero or greater than one: then that thumb is removed. If the user clicks between two existing thumbs: a new thumb is created if autoAdd is set to true. (If autoAdd is set to false: nothing happens.)

There are unimplemented methods in this class: doDoubleClick() and doPopup(). The UI will invoke these methods as needed; this gives the user a chance to edit the values represented at a particular point.

Also using the keyboard:

  • In a horizontal slider, the user can press modifier+left or modifer+right to insert a new thumb to the left/right of the currently selected thumb. (Where "modifier" refers to Toolkit.getDefaultTookit().getMenuShortcutKeyMask(). On Mac this is META, and on Windows this is CONTROL.) Likewise on a vertical slider the up/down arrow keys can be used to add thumbs.
  • The delete/backspace key can be used to remove thumbs.
  • In a horizontal slider, the down arrow key can be used to invoke doPopup(). This should invoke a JPopupMenu that is keyboard accessible, so the user should be able to navigate this component without a mouse. Likewise on a vertical slider the right arrow key should do the same.
  • The space bar or return key invokes doDoubleClick().

Because thumbs can be abstractly inserted, the values each thumb represents should be tween-able. That is, if there is a value at zero and a value at one, the call getValue(.5f) must return a value that is halfway between those values.

Also note that although the thumbs must always be between zero and one: the minimum and maximum thumbs do not have to be zero and one. The user can adjust them so the minimum thumb is, say, .2f, and the maximum thumb is .5f.

See Also:

  • Field Details

    • AUTOADD_PROPERTY

      public static final String AUTOADD_PROPERTY
      The property that controls whether clicking between thumbs automatically adds a thumb.

    • REMOVAL_ALLOWED

      public static final String REMOVAL_ALLOWED
      The property that controls whether the user can remove a thumb (either by dragging or with the delete key).

    • SELECTED_THUMB_PROPERTY

      public static final String SELECTED_THUMB_PROPERTY
      The property that is changed when setSelectedThumb() is called.

    • COLLISION_PROPERTY

      public static final String COLLISION_PROPERTY
      The property that is changed when setCollisionPolicy(c) is called.

    • INVERTED_PROPERTY

      public static final String INVERTED_PROPERTY
      The property that is changed when setInverted(b) is called.

    • THUMB_OVERLAP_PROPERTY

      public static final String THUMB_OVERLAP_PROPERTY
      The property that is changed when setInverted(b) is called.

    • THUMB_MINIMUM_PROPERTY

      public static final String THUMB_MINIMUM_PROPERTY
      The property that is changed when setMinimumThumbnailCount(b) is called.

    • ORIENTATION_PROPERTY

      public static final String ORIENTATION_PROPERTY
      The property that is changed when setOrientation(i) is called.

    • VALUES_PROPERTY

      public static final String VALUES_PROPERTY
      The property that is changed when setValues() is called. Note this is used when either the positions or the values are updated, because they need to be updated at the same time to maintain an exact one-to-one ratio.

    • ADJUST_PROPERTY

      public static final String ADJUST_PROPERTY
      The property that is changed when setValueIsAdjusting(b) is called.

    • PAINT_TICKS_PROPERTY

      public static final String PAINT_TICKS_PROPERTY
      The property that is changed when setPaintTicks(b) is called.

    • thumbPositions

      protected float[] thumbPositions
      The positions of the thumbs

    • values

      protected T[] values
      The values for each thumb

    • changeListeners

      List<ChangeListener> changeListeners
      ChangeListeners registered with this slider.

    • HORIZONTAL

      public static final int HORIZONTAL
      The orientation constant for a horizontal slider.
      See Also:

    • VERTICAL

      public static final int VERTICAL
      The orientation constant for a vertical slider.
      See Also:

  • Constructor Details

    • MultiThumbSlider

      public MultiThumbSlider(float[] thumbPositions, T[] values)
      Creates a new horizontal MultiThumbSlider.
      Parameters:
      thumbPositions - an array of values from zero to one.
      values - an array of values, each value corresponds to a value in thumbPositions.

    • MultiThumbSlider

      public MultiThumbSlider(int orientation, float[] thumbPositions, T[] values)
      Creates a new MultiThumbSlider.
      Parameters:
      orientation - must be HORIZONTAL or VERTICAL
      thumbPositions - an array of values from zero to one.
      values - an array of values, each value corresponds to a value in thumbPositions.

  • Method Details

    • getUI

      public MultiThumbSliderUi<T> getUI()
      Overrides:
      getUI in class JComponent

    • updateUI

      public void updateUI()
      Overrides:
      updateUI in class JComponent

    • setUI

      public void setUI(MultiThumbSliderUi<T> ui)
      Parameters:
      ui - slider

    • addChangeListener

      public void addChangeListener(ChangeListener l)
      This listener will be notified when the colors/positions of this slider are modified.

      Note you can also listen to these events by listening to the VALUES_PROPERTY, but this mechanism is provided as a convenience to resemble the JSlider model.

      Parameters:
      l - the ChangeListener to add.

    • removeChangeListener

      public void removeChangeListener(ChangeListener l)
      Removes a ChangeListener from this slider.
      Parameters:
      l - the listener to remove

    • fireChangeListeners

      protected void fireChangeListeners()
      Invokes all the ChangeListeners.

    • transferFocus

      public void transferFocus()
      Depending on which thumb is selected, this may shift the focus to the next available thumb, or it may shift the focus to the next focusable JComponent.
      Overrides:
      transferFocus in class Component

    • transferFocusBackward

      public void transferFocusBackward()
      Depending on which thumb is selected, this may shift the focus to the previous available thumb, or it may shift the focus to the previous focusable JComponent.
      Overrides:
      transferFocusBackward in class Component

    • createValueForInsertion

      public T createValueForInsertion(float pos)
      This creates a new value for insertion.

      If the pos argument is outside the domain of thumbs, then a value still needs to be returned.

      Parameters:
      pos - a position between zero and one
      Returns:
      a value that corresponds to the position pos

    • removeThumb

      public void removeThumb(int thumbIndex)
      Removes a specific thumb
      Parameters:
      thumbIndex - the thumb index to remove.

    • doDoubleClick

      public boolean doDoubleClick(int x, int y)
      An optional method subclasses can override to react to the user's double-click. When a thumb is double-clicked the user is trying to edit the value for that thumb. A double-click probably suggests the user wants a detailed set of controls to edit a value, such as a dialog.

      Note this method will be called with arguments (-1,-1) if the space bar or return key is pressed.

      By default this method does nothing, and returns false

      Note the (x,y) information passed to this method is only provided so subclasses can position components (such as a JPopupMenu). It can be assumed for a double-click event that the user has selected a thumb (since one click will click/create a thumb) and intends to edit the currently selected thumb.

      Parameters:
      x - the x-value of the mouse click location
      y - the y-value of the mouse click location
      Returns:
      true if this event was consumed, or acted upon. false if this is unimplemented.

    • doPopup

      public boolean doPopup(int x, int y)
      An optional method subclasses can override to react to the user's request for a contextual menu. When a thumb is right-clicked the user is trying to edit the value for that thumb. A right-click probably suggests the user wants very quick, simple options to adjust a thumb.

      By default this method does nothing, and returns false

      Parameters:
      x - the x-value of the mouse click location
      y - the y-value of the mouse click location
      Returns:
      true if this event was consumed, or acted upon. false if this is unimplemented.

    • isPaintTicks

      public boolean isPaintTicks()
      Tells if tick marks are to be painted.
      Returns:
      whether ticks should be painted on this slider.

    • setPaintTicks

      public void setPaintTicks(boolean b)
      Turns on/off the painted tick marks for this slider.

      This triggers a PropertyChangeEvent for PAINT_TICKS_PROPERTY.

      Parameters:
      b - whether tick marks should be painted

    • addThumb

      public int addThumb(float pos)
      This creats and inserts a thumb at a position indicated.

      This method relies on the abstract getValue(float) to determine what value to put at the new thumb location.

      Parameters:
      pos - the new thumb position
      Returns:
      the index of the newly created thumb

    • setValueIsAdjusting

      public void setValueIsAdjusting(boolean b)
      This is used to notify other objects when the user is in the process of adjusting values in this slider.

      A listener may not want to act on certain changes until this property is false if it is expensive to process certain changes.

      This triggers a PropertyChangeEvent for ADJUST_PROPERTY.

      Parameters:
      b - new value

    • isValueAdjusting

      public boolean isValueAdjusting()
      true if the user is current modifying this component.
      Returns:
      the value of the adjusting property

    • getThumbPositions

      public float[] getThumbPositions()
      The thumb positions for this slider.

      There is a one-to-one correspondence between this array and the getValues() array.

      This array is always sorted in ascending order.

      Returns:
      an array of the positions of thumbs.

    • getValues

      public T[] getValues()
      The values for thumbs for this slider.

      There is a one-to-one correspondence between this array and the getThumbPositions() array.

      Returns:
      an array of the values associated with each thumb.

    • setValues

      public void setValues(float[] thumbPositions, T[] values)
      This assigns new positions/values for the thumbs in this slider. The two must be assigned at exactly the same time, so there is always the same number of thumbs/sliders.

      This triggers a PropertyChangeEvent for VALUES_PROPERTY, and possibly for the SELECTED_THUMB_PROPERTY if that had to be adjusted, too.

      Parameters:
      thumbPositions - an array of the new position of each thumb
      values - an array of the value associated with each thumb
      Throws:
      IllegalArgumentException - if the size of the arrays are different, or if the thumbPositions array is not sorted in ascending order.

    • getThumbCount

      public int getThumbCount()
      The number of thumbs in this slider.
      Returns:
      the number of thumbs.

    • setSelectedThumb

      public void setSelectedThumb(int index)
      Assigns the currently selected thumb. A value of -1 indicates that no thumb is currently selected.

      A slider should always have a selected thumb if it has the keyboard focus, though, so be careful when you modify this.

      This triggers a PropertyChangeEvent for SELECTED_THUMB_PROPERTY.

      Parameters:
      index - the new selected thumb

    • getSelectedThumb

      public int getSelectedThumb()
      Returns the selected thumb index, or -1 if this component doesn't have the keyboard focus.
      Returns:
      the selected thumb index

    • getSelectedThumb

      public int getSelectedThumb(boolean ignoreIfUnfocused)
      Returns the currently selected thumb index.

      Note this might be -1, indicating that there is no selected thumb.

      It is recommend you use the getSelectedThumb() method most of the time. This method is made public so UI's can provide a better user experience as this component gains and loses focus.

      Parameters:
      ignoreIfUnfocused - if this component doesn't have focus and this is true, then this returns -1. If this is false then this returns the internal value used to store the selected index, but the user may not realize this thumb is "selected".
      Returns:
      the selected thumb

    • setAutoAdding

      public void setAutoAdding(boolean b)
      Controls whether thumbs are automatically added when the user clicks in a space that doesn't already have a thumb.
      Parameters:
      b - whether auto adding is active or not

    • isAutoAdding

      public boolean isAutoAdding()
      Returns:
      whether thumbs are automatically added when the user clicks in a space that doesn't already have a thumb.

    • getOrientation

      public int getOrientation()
      The orientation of this slider.
      Returns:
      HORIZONTAL or VERTICAL

    • setOrientation

      public void setOrientation(int i)
      Reassign the orientation of this slider.
      Parameters:
      i - must be HORIZONTAL or VERTICAL

    • isInverted

      public boolean isInverted()
      Returns:
      whether this slider is inverted or not.

    • setInverted

      public void setInverted(boolean b)
      Assigns whether this slider is inverted or not.
      Parameters:
      b - inverted slider or not This triggers a PropertyChangeEvent for INVERTED_PROPERTY.

    • getCollisionPolicy

      public MultiThumbSlider.Collision getCollisionPolicy()

    • setCollisionPolicy

      public void setCollisionPolicy(MultiThumbSlider.Collision c)

    • isThumbRemovalAllowed

      public boolean isThumbRemovalAllowed()

    • setThumbRemovalAllowed

      public void setThumbRemovalAllowed(boolean b)

    • setMinimumThumbnailCount

      public void setMinimumThumbnailCount(int i)

    • getMinimumThumbnailCount

      public int getMinimumThumbnailCount()

    • setThumbOverlap

      public void setThumbOverlap(boolean i)

    • isThumbOverlap

      public boolean isThumbOverlap()