Package com.bric.multislider

Class 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:
    Serialized Form

    • Field Detail

      • 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:
        Constant Field Values

      • VERTICAL

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

    • Constructor Detail

      • 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 Detail

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

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