/** * @(#)SliderView.java 2.6.0 29 August 2007 * * Copyright 2007 * College of Computer and Information Science * Northeastern University * Boston, MA 02115 * * The Java Power Tools software may be used for educational * purposes as long as this copyright notice is retained intact * at the top of all source files. * * To discuss possible commercial use of this software, * contact Richard Rasala at Northeastern University, * College of Computer and Information Science, * 617-373-2462 or rasala@ccs.neu.edu. * * The Java Power Tools software has been designed and built * in collaboration with Viera Proulx and Jeff Raab. * * Should this software be modified, the words "Modified from * Original" must be included as a comment below this notice. * * All publication rights are retained. This software or its * documentation may not be published in any media either * in whole or in part without explicit permission. * * This software was created with support from Northeastern * University and from NSF grant DUE-9950829. */ package edu.neu.ccs.gui; import edu.neu.ccs.*; import edu.neu.ccs.util.*; import java.awt.*; import java.awt.event.*; import java.awt.geom.*; import java.text.ParseException; /** *

Class SliderView permits the construction of * a slider with pixel-level control of the size of the slider * track. The caller can therefore control the relationship * between the minimum and maximum values represented by the * slider and the physical implementation in pixels. This can * permit users to make slider selections with more accuracy.

* *

The SliderView code was completely rewritten * for version 2.6.0. A few older methods that are now obsolete * have been retained for backward compatibility as is noted in * the comments. This class no longer depends on the Java class * JSlider.

* *

In addition to pixel-level control of the size of the slider, * SliderView offers several advantages over the Java * class JSlider.

* * * *

The constructors for class SliderView allow * the following options:

* * * *

Remarks on the minimum and maximum settings and the * track pixels setting:

* * * *

After construction, the caller may add one or more actions * that will be performed in any of the following 3 situations:

* * * *

These actions should normally behave as listeners, that is, * they may query information about the slider from methods such * as getValue and getTrackLocation but * they should normally not call methods that change the slider * state. These actions are intended to be used to control other * objects in the program, especially, in the GUI.

* *

The actions are explicity forbidden to call four methods: * setValue, setTrackLocation, * setViewState, and reset. The * reason for this explict ban is that the four methods invoke * the actions internally and therefore calling them from the * actions will set up a recursive infinite loop.

* *

In unusual situations, the actions may change slider state * via calls to two helper methods setValueHelper * and setTrackLocationHelper which do not invoke * the actions. This facility should be used with great caution * as what happens may be confusing to the interactive user.

* *

Final comment: When the mouse is released after a click * or a slide, both the sliding action and the release action * will be performed. This policy guarantees that the sliding * action is performed at least once between the mouse press * on the thumb or track and the subsequent mouse release.

* * @author Richard Rasala * @author Jeff Raab * @version 2.6.0 * @since 1.0 */ public class SliderView extends BasePane implements TypedView { /** The minimum permitted pixels value: 20. */ public static final int MINIMUM_PIXELS = 20; /** The thumb size: 9. */ public static final int THUMB_SIZE = 9; /** The thumb size plus 1. */ public static final int THUMB_PLUS = THUMB_SIZE + 1; /** The track thickness: 6. */ public static final int TRACK_THICK = 6; /** The track border thickness: 2. */ public static final int TRACK_BORDER_THICK = 2; /** The default major tick size: 8. */ public static final int MAJOR_TICK_SIZE = 8; /** The default minor tick size: 4. */ public static final int MINOR_TICK_SIZE = 4; /** Stroke of size 2: BasicStroke(2). */ public static final Stroke STROKE2 = new BasicStroke(2); /** The ID for a press action event. */ public static final int PRESS_ACTION = 0; /** The ID for a sliding action event. */ public static final int SLIDING_ACTION = 1; /** The ID for a release action event. */ public static final int RELEASE_ACTION = 2; /** *

The slider thumb shape.

*/ protected Shape thumbShape = null; /** *

The slider thumb.

*/ protected ShapePaintable thumb = null; /** *

The ordinary fill paint for the thumb.

* *

Default: Color.white.

*/ protected Paint ordinaryThumbPaint = Color.white; /** *

The selected fill paint for the thumb.

* *

Default: Color.red.

*/ protected Paint selectedThumbPaint = Color.red; /** *

The slider track rect.

*/ protected XRect trackRect = null; /** *

The slider track.

*/ protected ShapePaintable track = null; /** *

The fill paint for the track.

* *

Default: Color.yellow.

*/ protected Paint trackPaint = Color.yellow; /** *

The slider track border rect.

*/ protected XRect trackBorderRect = null; /** *

The slider track border.

*/ protected ShapePaintable trackBorder = null; /** *

The common color for lines, borders, and text labels.

* *

Default: Color.black.

*/ protected Color commonColor = Color.black; /** *

The paintable sequence for slider tick marks.

* *

An empty sequence is constructed in this class.

* *

If majorTicks and/or minorTicks is positive then * the corresponding default methods below will * populate this paintable sequence with ticks.

* *

If both majorTicks and minorTicks are zero, then * the caller has complete control of what ticks, * if any, will be installed.

*/ protected final PaintableSequence tickSequence = new PaintableSequence(); /** *

The paintable sequence for slider labels.

* *

An empty sequence is constructed in this class.

* *

If majorTicks is positive, then the default labels * will be installed at the corresponding ticks.

* *

If majorTicks is zero, then the caller has complete * control of what labels, if any, will be installed.

*/ protected final PaintableSequence labelSequence = new PaintableSequence(); /** *

The paintable sequence for more general * Paintable objects.

* *

The caller has complete control of what objects, * if any, will be installed.

*/ protected final PaintableSequence objectSequence = new PaintableSequence(); /** *

The paintable sequence for all of the paintables * in the slider GUI including the thumb, the track, * the major and minor tick marks, and the labels.

* *

Populated by initializeSequence(). * This sequence contains other sequences as items. * These other sequences are populated by their own * methods.

*/ protected final PaintableSequence mainSequence = new PaintableSequence(); /** *

Once initialized by freezeBounds(), * this rectangle contains the bounds of the sequence * mainSequence.

*/ protected XRect mainBounds = null; /** * The x-coordinate of the top-left corner of the * main bounds (as an integer). */ protected int cornerX = 0; /** * The y-coordinate of the top-left corner of the * main bounds (as an integer). */ protected int cornerY = 0; /** The paintable component to hold the main sequence. */ protected PaintableComponent mainComponent = new PaintableComponent(mainSequence); /** The mouse adapter of the main component. */ protected MouseActionAdapter adapter = mainComponent.getMouseActionAdapter(); /** * The x-coordinate of the current mouse position * as adjusted by cornerX to be in the coordinate * system of the main sequence. */ protected int mouseX = 0; /** * The y-coordinate of the current mouse position * as adjusted by cornerY to be in the coordinate * system of the main sequence. */ protected int mouseY = 0; /** The mouse press action. */ protected MouseAction mousePressAction = new MouseAction() { public void mouseActionPerformed(MouseEvent evt) { mousePress(evt); } }; /** The mouse sliding action. */ protected MouseAction mouseSlidingAction = new MouseAction() { public void mouseActionPerformed(MouseEvent evt) { mouseSliding(evt); } }; /** The mouse release action. */ protected MouseAction mouseReleaseAction = new MouseAction() { public void mouseActionPerformed(MouseEvent evt) { mouseRelease(evt); } }; /** * The caller-defined actions performed * when the slider thumb is pressed. */ protected ActionSequence pressActions = new ActionSequence(); /** * The caller-defined actions performed * when the slider thumb is sliding. */ protected ActionSequence slidingActions = new ActionSequence(); /** * The caller-defined actions performed * when the slider thumb is released. */ protected ActionSequence releaseActions = new ActionSequence(); /** *

The standard event that will be passed to the sequence * pressActions when the mouse is pressed in * the active area of the slider (thumb or track).

* *

The source is this.

* *

The ID is PRESS_ACTION.

* *

The command string is empty.

*/ public final ActionEvent pressEvent = new ActionEvent(this, PRESS_ACTION, ""); /** *

The standard event that will be passed to the sequence * slidingActions when the mouse is sliding * after being pressed in the active area of the slider * (thumb or track).

* *

The source is this.

* *

The ID is SLIDING_ACTION.

* *

The command string is empty.

*/ public final ActionEvent slidingEvent = new ActionEvent(this, SLIDING_ACTION, ""); /** *

The standard event that will be passed to the sequence * releaseActions when the mouse is released * after being pressed in the active area of the slider * (thumb or track).

* *

The source is this.

* *

The ID is RELEASE_ACTION.

* *

The command string is empty.

*/ public final ActionEvent releaseEvent = new ActionEvent(this, RELEASE_ACTION, ""); /** * The text field view that will echo the current * conceptual value of the slider. This view may * also be used for input of the slider value. */ protected TextFieldView valueTFV = new TextFieldView(); /** * The action to set the slider value from the * value text field view. */ protected SimpleAction setValueFromValueTFV = new SimpleAction() { public void perform() { setValueFromValueTFV(); } }; /** * The slider orientation which should be either * HORIZONTAL or VERTICAL. */ protected int orientation = HORIZONTAL; /** *

The track minimum value.

* *

If the caller enters a minimum larger than the maximum * then that will reverse the order on the slider.

* *

It is required that minimum and maximum be unequal. */ protected int minimum; /** *

The track maximum value.

* *

If the caller enters a minimum larger than the maximum * then that will reverse the order on the slider.

* *

It is required that minimum and maximum be unequal. */ protected int maximum; /** * The difference (maximum - minimum). */ protected int delta; /** *

The value of the slider, that is, what will be returned * by the call getValue().

* *

The value should be between minimum and maximum.

*/ protected int value; /** The default value for this slider. */ protected int defaultValue; /** *

The track pixels, that is, the size of the track * along its major direction.

* *

It is required that pixels be at least * MINIMUM_PIXELS.

*/ protected int pixels; /** *

The track limit, that is, the last valid location * on the track along its major direction.

* *

Equivalent to (pixels - 1).

*/ protected int limit; /** *

The thumb location along the track.

* *

The location should be between 0 and limit.

*/ protected int location; /** The scale factor for locationToValue. */ protected double f_loc_to_val; /** The translation for locationToValue. */ protected double t_loc_to_val; /** The scale factor for valueToLocation. */ protected double f_val_to_loc; /** The translation for valueToLocation. */ protected double t_val_to_loc; /** *

The major ticks setting.

* *

If zero, then major ticks and labels will not be shown * automatically but may be added by the caller.

*/ protected int majorTicks; /** *

The minor ticks setting.

* *

If zero, then minor ticks will not be shown * automatically but may be added by the caller.

*/ protected int minorTicks; /** *

The dragging parameter will be set to true if and * only if the user is currently dragging the thumb. * This is only used internally.

*/ protected boolean dragging = false; /** The property list for this view object. */ protected InputProperties properties = new InputProperties(); /** *

Constructs a default SliderView.

* *

The orientation will be horizontal.

* *

The minimum will be 0.

* *

The maximum will be 100.

* *

The initial value will be 50.

* *

The size of the track will be 101 pixels. To control * the track size you must use one of the constructors that * include the pixels parameter.

* *

If this constructor is used, there will be no automatic * major ticks, minor ticks, or labels. These may be added * by the caller if desired by using the methods of this * class.

* *

This constructor will show the text field in which the * value of the slider is automatically displayed.

* *

This constructor is included for backward compatibility * and to permit experiments since no parameters are required.

*/ public SliderView() { this(HORIZONTAL, 0, 100, 50, 101, 0, 0, null, null, null, null, true); } /** *

Constructs a SliderView with the given * orientation which must be HORIZONTAL or * VERTICAL.

* *

The minimum will be 0.

* *

The maximum will be 100.

* *

The initial value will be 50.

* *

The size of the track will be 101 pixels. To control * the track size you must use one of the constructors that * include the pixels parameter.

* *

If this constructor is used, there will be no automatic * major ticks, minor ticks, or labels. These may be added * by the caller if desired by using the methods of this * class.

* *

This constructor will show the text field in which the * value of the slider is automatically displayed.

* *

This constructor is included for backward compatibility.

*/ public SliderView(int orientation) { this(orientation, 0, 100, 50, 101, 0, 0, null, null, null, null, true); } /** *

Constructs a SliderView with the given * parameters.

* *

The orientation controls the orientation * of the slider in the GUI and should be either * HORIZONTAL or VERTICAL.

* *

The minimum and maximum * parameters determine the minimum and maximum values that * the slider can return via the getValue() * method. It is permissible for these values to be in the * opposite order and in that case the slider will work in * the opposite order.

* *

The value paramter is the initial slider * value, except that, if it is out of range, then it will * be forced into range.

* *

The size of the track will be 101 pixels. To control * the track size you must use one of the constructors that * include the pixels parameter.

* *

If this constructor is used, there will be no automatic * major ticks, minor ticks, or labels. These may be added * by the caller if desired by using the methods of this * class.

* *

This constructor will show the text field in which the * value of the slider is automatically displayed.

* *

Throws IllegalArgumentException * if minimum equals maximum * or if pixels is less than MINIMUM_PIXELS. * *

This constructor is included for backward compatibility.

*/ public SliderView(int orientation, int minimum, int maximum, int value) { this(orientation, minimum, maximum, value, 101, 0, 0, null, null, null, null, true); } /** *

Constructs a SliderView with the given * parameters.

* *

The orientation controls the orientation * of the slider in the GUI and should be either * HORIZONTAL or VERTICAL.

* *

The minimum and maximum * parameters determine the minimum and maximum values that * the slider can return via the getValue() * method. It is permissible for these values to be in the * opposite order and in that case the slider will work in * the opposite order.

* *

The value paramter is the initial slider * value, except that, if it is out of range, then it will * be forced into range.

* *

The pixelsparameter is the physical size * of the slider track in the direction of slider motion.

* *

If this constructor is used, there will be no automatic * major ticks, minor ticks, or labels. These may be added * by the caller if desired by using the methods of this * class.

* *

This constructor will show the text field in which the * value of the slider is automatically displayed.

* *

Throws IllegalArgumentException * if minimum equals maximum * or if pixels is less than MINIMUM_PIXELS. */ public SliderView (int orientation, int minimum, int maximum, int value, int pixels) { this(orientation, minimum, maximum, value, pixels, 0, 0, null, null, null, null, true); } /** *

Constructs a SliderView with the given * parameters.

* *

The orientation controls the orientation * of the slider in the GUI and should be either * HORIZONTAL or VERTICAL.

* *

The minimum and maximum * parameters determine the minimum and maximum values that * the slider can return via the getValue() * method. It is permissible for these values to be in the * opposite order and in that case the slider will work in * the opposite order.

* *

The value paramter is the initial slider * value, except that, if it is out of range, then it will * be forced into range.

* *

The pixelsparameter is the physical size * of the slider track in the direction of slider motion.

* *

The majorTicksparameter controls the * position of the major ticks along the slider and the * associated automatic labels. If this parameter is 0, * then major ticks and labels will not be automatically * drawn. These decorations may be supplied manually by * the caller using methods in the class.

* *

The minorTicksparameter controls the * position of the minor ticks along the slider. If * this parameter is 0, then minor ticks will not be * automatically drawn.

* *

This constructor will show the text field in which the * value of the slider is automatically displayed.

* *

Throws IllegalArgumentException * if minimum equals maximum * or if pixels is less than MINIMUM_PIXELS. */ public SliderView (int orientation, int minimum, int maximum, int value, int pixels, int majorTicks, int minorTicks) { this(orientation, minimum, maximum, value, pixels, majorTicks, minorTicks, null, null, null, null, true); } /** *

Constructs a SliderView with the given * parameters.

* *

The orientation controls the orientation * of the slider in the GUI and should be either * HORIZONTAL or VERTICAL.

* *

The minimum and maximum * parameters determine the minimum and maximum values that * the slider can return via the getValue() * method. It is permissible for these values to be in the * opposite order and in that case the slider will work in * the opposite order.

* *

The value paramter is the initial slider * value, except that, if it is out of range, then it will * be forced into range.

* *

The pixelsparameter is the physical size * of the slider track in the direction of slider motion.

* *

The majorTicksparameter controls the * position of the major ticks along the slider and the * associated automatic labels. If this parameter is 0, * then major ticks and labels will not be automatically * drawn. These decorations may be supplied manually by * the caller using methods in the class.

* *

The minorTicksparameter controls the * position of the minor ticks along the slider. If * this parameter is 0, then minor ticks will not be * automatically drawn.

* *

This constructor allows the caller to set the various * paints and colors used in the GUI. If a parameter is * null then the default will be used.

* *

The paint and color defaults are:

* * * *

The common color is used for tick marks, borders, and text.

* *

This constructor will show the text field in which the * value of the slider is automatically displayed if the * showValueTFV parameter is set to true.

* *

Throws IllegalArgumentException * if minimum equals maximum * or if pixels is less than MINIMUM_PIXELS. */ public SliderView (int orientation, int minimum, int maximum, int value, int pixels, int majorTicks, int minorTicks, Paint ordinaryThumbPaint, Paint selectedThumbPaint, Paint trackPaint, Color commonColor, boolean showValueTFV) { initializeNumerics (orientation, minimum, maximum, value, pixels, majorTicks, minorTicks); initializePaints (ordinaryThumbPaint, selectedThumbPaint, trackPaint, commonColor); initializeValueTFV(); initializeThumb(); initializeTrack(); installDefaultMajorTicks(); installDefaultMinorTicks(); installDefaultLabels(); initializeMainSequence(); initializeMouse(); installMainPanel(showValueTFV); } /** *

Initializes important numerical parameters.

* *

Initializes the orientation so that it must be * either HORIZONTAL * or VERTICAL.

* *

Initializes the numeric relationships between * the conceptual slider data (minimum, maximum, value) * and the pixel data (pixels, limit, location).

* *

Initializes the tick settings. Furthermore, if * both tick settings are positive, then minorTicks * is forced to be a divisor of majorTicks.

* *

Throws IllegalArgumentException * if minimum equals maximum * or if pixels is less than MINIMUM_PIXELS. */ protected final void initializeNumerics (int orientation, int minimum, int maximum, int value, int pixels, int majorTicks, int minorTicks) { String message = ""; if (minimum == maximum) message = "Slider minimum cannot equal slider maximum\n"; if (pixels < MINIMUM_PIXELS) message += "Slider pixels must be at least " + MINIMUM_PIXELS + "\n"; if (message.length() > 0) throw new IllegalArgumentException(message); if (orientation != VERTICAL) orientation = HORIZONTAL; this.orientation = orientation; this.minimum = minimum; this.maximum = maximum; delta = maximum - minimum; value = getValidValue(value); this.value = value; defaultValue = value; this.pixels = pixels; limit = pixels - 1; f_loc_to_val = delta; f_loc_to_val /= limit; t_loc_to_val = minimum; f_val_to_loc = limit; f_val_to_loc /= delta; t_val_to_loc = - f_val_to_loc * minimum; location = valueToLocation(value); majorTicks = (majorTicks > 0) ? majorTicks : 0; minorTicks = (minorTicks > 0) ? minorTicks : 0; if ((majorTicks > 0) && (minorTicks > 0)) minorTicks = (int) MathUtilities.GCD(majorTicks, minorTicks); this.majorTicks = majorTicks; this.minorTicks = minorTicks; } /** *

Performs the paint and color initializations.

* *

This method which is called by the most elaborate constructor * allows the caller to set the various paints and colors used in * the GUI. If a parameter is null then the default * will be used.

* *

The paint and color defaults are:

* * * *

The common color is used by tick marks, borders, and text.

* *

There are individual public methods to reset each particular * paint or color after a constructor has been called.

*/ protected final void initializePaints (Paint ordinaryThumbPaint, Paint selectedThumbPaint, Paint trackPaint, Color commonColor ) { if (ordinaryThumbPaint != null) this.ordinaryThumbPaint = ordinaryThumbPaint; if (selectedThumbPaint != null) this.selectedThumbPaint = selectedThumbPaint; if (trackPaint != null) this.trackPaint = trackPaint; if (commonColor != null) this.commonColor = commonColor; } /** Performs the initializations for the value text field. */ protected final void initializeValueTFV() { valueTFV.addActionListener(setValueFromValueTFV); valueTFV.setFont(labelFont); valueTFV.setForeground(commonColor); valueTFV.setSelectedTextColor(commonColor); String minString = "" + minimum; String maxString = "" + maximum; int n1 = minString.length(); int n2 = maxString.length(); String sample = (n1 > n2) ? minString : maxString; int width = TextFieldView.getSampleWidth(labelFont, sample); valueTFV.setPreferredWidth(width); } /** Performs the initializations for the thumb. */ protected final void initializeThumb() { int s = THUMB_SIZE; int p = THUMB_PLUS; PlotMarkAlgorithm alg; if (orientation == HORIZONTAL) { alg = PlotMarkAlgorithm.ThumbS; thumbShape = alg.makeShape(0, s, s); } else { alg = PlotMarkAlgorithm.ThumbE; thumbShape = alg.makeShape(s, 0, s); } thumb = new ShapePaintable (thumbShape, PaintMode.FILL_DRAW, ordinaryThumbPaint, commonColor, STROKE2); thumb.setDefaultOriginalBounds2D(new XRect(-p, -p, 2*p, 2*p)); thumb.setDefaultOriginalCenter(new XPoint2D(0, 0)); } /** *

Performs the initializations for the track and track border.

* *

Sets the original default bounds to allow for the thumb.

*/ protected final void initializeTrack() { int t = TRACK_THICK; int h = t/2; int b = TRACK_BORDER_THICK; int p = THUMB_PLUS; XRect bounds = null; if (orientation == HORIZONTAL) { trackRect = new XRect(0, -h, pixels, t); trackBorderRect = new XRect(-b, -(h + b), pixels + 2*b, t + 2*b); bounds = new XRect(-p, -p, pixels + 2*p, 2*p); } else { trackRect = new XRect(-h, 0, t, pixels); trackBorderRect = new XRect(-(h + b), -b, t + 2*b, pixels + 2*b); bounds = new XRect(-p, -p, 2*p, pixels + 2*p); } track = new ShapePaintable (trackRect, PaintMode.FILL, trackPaint); trackBorder = new ShapePaintable (trackBorderRect, PaintMode.FILL, commonColor); track.setDefaultOriginalBounds2D(bounds); trackBorder.setDefaultOriginalBounds2D(bounds); } /** *

Appends all items to the main paintable sequence.

* *

These are in order:

* * * *

This order is the top-to-bottom order of painting. * In particular, any general decorations will be below * all other objects in the GUI.

*/ protected final void initializeMainSequence() { mainSequence.appendPaintable(thumb); mainSequence.appendPaintable(track); mainSequence.appendPaintable(trackBorder); mainSequence.appendPaintable(tickSequence); mainSequence.appendPaintable(labelSequence); mainSequence.appendPaintable(objectSequence); resetThumb(); } /** Initializes the mouse behavior. */ protected final void initializeMouse() { adapter.addMousePressedAction(mousePressAction); adapter.addMouseDraggedAction(mouseSlidingAction); adapter.addMouseReleasedAction(mouseReleaseAction); } /** *

Installs the main panel with the slider and optionally * the value text field.

* *

If showValueTFV is true then the text field * in which the value of the slider is automatically displayed * will be installed in the GUI.

*/ protected final void installMainPanel(boolean showValueTFV) { TablePanel mainPanel = null; Object[] stuff = null; if (showValueTFV) stuff = new Object[] { mainComponent, valueTFV }; else stuff = new Object[] { mainComponent }; if (orientation == HORIZONTAL) mainPanel = new HTable(stuff, gap, gap, NORTH); else mainPanel = new VTable(stuff, gap, gap, WEST); addObject(mainPanel); updateValueTFV(); } /** *

Creates the paintable for one tick.

* * @param val the tick position in value coordinates * @param size the tick size */ public final ShapePaintable makeTick(int val, int size) { val = getValidValue(val); int loc = valueToLocation(val); int p = THUMB_PLUS + gap; int q = p + size; XLine2D line = new XLine2D(); if (orientation == HORIZONTAL) { line.setLine(loc, p, loc, q); } else { line.setLine(p, loc, q, loc); } ShapePaintable paintable = new ShapePaintable(line, PaintMode.DRAW, null, commonColor, STROKE2); return paintable; } /** *

Returns the array of slider values that will be * used to generate the tick value positions based on * the given tick spacing and the internal minimum * and maximum.

* *

For example, if minimum = 1, maximum = 99, and * spacing = 10, the following array of values will * be returned:

* * 
    1, 10, 20, 30, 40, 50, 60, 70, 80, 90, 99
* *

Thus, the tick value positions strictly between * minimum and maximum are multiples of the spacing.

* *

This algorithm in NOT the one used in the Java * JSlider class.

* *

This method may be overridden in a derived class * if a different algorithm is desired. Alternatively, * several methods below accept an explicit array of * values and a caller may supply whatever values are * desired.

* *

Returns an empty array if spacing <= 0; * * @param spacing the tick spacing in value coordinates */ public int[] getTickValues(int spacing) { if (spacing <= 0) return new int[0]; int[] values = null; int a = minimum % spacing; if (a < 0) a += spacing; int b = maximum % spacing; if (b < 0) b += spacing; int count = 0; int s = minimum; int t = maximum; if (delta > 0) { if (a > 0) { count++; s += (spacing - a); } if (b > 0) { count++; t -= b; } if (s <= t) { count += ((t - s) / spacing) + 1; } values = new int[count]; int k = 0; if (a > 0) { values[k] = minimum; k++; } while (s <= t) { values[k] = s; k++; s += spacing; } if (b > 0) { values[k] = maximum; k++; } } else { if (a > 0) { count++; s -= a; } if (b > 0) { count++; t += (spacing - b); } if (s >= t) { count += ((s - t) / spacing) + 1; } values = new int[count]; int k = 0; if (a > 0) { values[k] = minimum; k++; } while (s >= t) { values[k] = s; k++; s -= spacing; } if (b > 0) { values[k] = maximum; k++; } } return values; } /** *

Installs ticks of the given size at the given value * positions.

* * @param values the tick positions in value coordinates * @param size the tick size */ public final void installTicks(int[] values, int size) { if ((values == null) || (size <= 0)) return; int n = values.length; for (int i = 0; i < n; i++) tickSequence.appendPaintable(makeTick(values[i], size)); } /** *

Installs the default major ticks provided that the * majorTicks value is positive. Does nothing if * majorTicks is zero.

* *

Calls getTickValues to get the * tick positions.

* *

Uses MAJOR_TICK_SIZE for the tick size.

*/ public final void installDefaultMajorTicks() { if (majorTicks <= 0) return; int[] values = getTickValues(majorTicks); installTicks(values, MAJOR_TICK_SIZE); } /** *

Installs the default minor ticks provided that the * minorTicks value is positive. Does nothing if * minorTicks is zero.

* *

Calls getTickValues to get the * tick positions.

* *

Uses MINOR_TICK_SIZE for the tick size.

*/ public final void installDefaultMinorTicks() { if (minorTicks <= 0) return; int[] values = getTickValues(minorTicks); installTicks(values, MINOR_TICK_SIZE); } /** *

Installs standard major tick marks following the * very simple algorithm available in this class prior * to version 2.6.0.

* *

Since the installation of tick marks is now made * automatic in several constructors, this method will * do nothing if either majorTicks or * minorTicks is positive. If both of * these settings are zero, then this method will make * major ticks using a spacing of (1/10) of the * difference between maximum and * minimum. It will not make minor ticks.

* *

This method is retained for backward compatibility * but is not recommended for new code.

*/ public final void installStandardTicks() { if ((majorTicks > 0) || (minorTicks > 0)) return; majorTicks = Math.abs(delta/10); installDefaultMajorTicks(); majorTicks = 0; } /** *

Creates the paintable for one label.

* *

This method allows space for a tick whose size is * given by the size parameter. If this parameter is * zero, then no allowance is made for a tick.

* * @param val the label position in value coordinates * @param label the label as a String * @param size the tick size */ public final TextPaintable makeLabel(int val, String label, int size) { val = getValidValue(val); int loc = valueToLocation(val); int p = THUMB_PLUS + gap; if (size > 0) p += size + gap; TextPaintable paintable = null; if (orientation == HORIZONTAL) { paintable = new TextPaintable (label, labelFont, commonColor, TextAnchor.CENTER_ASCENTLINE, loc, p); } else { paintable = new TextPaintable (label, labelFont, commonColor, TextAnchor.LEFT_ASCENTLINE, p, loc - fontSize/2 + 1); } return paintable; } /** *

Returns the array of numeric Strings corresponding * to the array of integer values.

* *

Returns an empty array if the parameter array is * null.

* * @param values the integer values to convert to String */ public final String[] makeLabelStrings(int[] values) { if (values == null) return new String[0]; int length = values.length; String[] labels = new String[length]; for (int i = 0; i < length; i++) labels[i] = "" + values[i]; return labels; } /** *

Returns the array of TextPaintable labels * positioned at the given value positions and using the * given String labels.

* *

Returns an empty array if either parameter array is * null.

* *

If the parameter arrays have unequal length, then * the minimum of the lengths is used in the construction.

* *

This method allows space for a tick whose size is * given by the size parameter. If this parameter is * zero, then no allowance is made for a tick.

* * @param values the value positions for the labels * @param labels the label data as String * @param size the tick size */ public final TextPaintable[] makeLabels (int[] values, String[] labels, int size) { if ((values == null) || (labels == null)) return new TextPaintable[0]; int a = values.length; int b = labels.length; int n = Math.min(a, b); TextPaintable[] tp = new TextPaintable[n]; for (int i = 0; i < n; i++) tp[i] = makeLabel(values[i], labels[i], size); return tp; } /** *

Makes an array of TextPaintable labels * using the given value positions and String labels and * installs the created labels in the internal paintable * sequence that is associated with labels.

* *

This method allows space for a tick whose size is * given by the size parameter. If this parameter is * zero, then no allowance is made for a tick.

* * @param values the value positions for the labels * @param labels the label data as String * @param size the tick size */ public final void installLabels (int[] values, String[] labels, int size) { labelSequence.appendSequence(makeLabels(values, labels, size)); } /** *

Installs the default labels provided that the * majorTicks value is positive. Does nothing if * majorTicks is zero.

* *

Calls getTickValues to get the * tick positions.

* *

Then calls makeLabelStrings to * get the String labels.

* *

Assumes MAJOR_TICK_SIZE as the * tick size.

* *

Then calls installLabels.

*/ public final void installDefaultLabels() { if (majorTicks <= 0) return; int[] values = getTickValues(majorTicks); String[] labels = makeLabelStrings(values); installLabels(values, labels, MAJOR_TICK_SIZE); } /** *

Installs standard labels following the * very simple algorithm available in this class prior * to version 2.6.0.

* *

Since the installation of labels is now made * automatic in several constructors, this method will * do nothing if either majorTicks or * minorTicks is positive. If both of * these settings are zero, then this method will make * labels using a spacing of (1/10) of the * difference between maximum and * minimum.

* *

This method is retained for backward compatibility * but is not recommended for new code.

*/ public void installStandardLabels() { if ((majorTicks > 0) || (minorTicks > 0)) return; majorTicks = Math.abs(delta/10); installDefaultLabels(); majorTicks = 0; } /** *

Installs the given Paintable objects as * decorations in the internal paintable sequence that is * associated with objects.

* *

This method gives the caller complete control of what * Paintable objects are placed as decorations * in the slider GUI and where.

* *

These decorations will be below all other objects in * the GUI. It is recommended that the caller experiment * carefully with the placement of decorations to avoid * visual conflicts.

* *

This method supports rather esoteric needs and will * likely not be used by most callers of this class.

* * @param objects the paintable objects to place in the GUI */ public final void installObjects(Paintable[] objects) { objectSequence.appendSequence(objects); } /** *

If the given value is between minimum and maximum, then * return that value; otherwise return the closest valid * value to the given value.

* *

This method is a helper method that does not change the * slider state.

* * @param val the value to test */ public final int getValidValue(int val) { if (delta > 0) { if (val < minimum) return minimum; if (val > maximum) return maximum; return val; } else { if (val > minimum) return minimum; if (val < maximum) return maximum; return val; } } /** *

If the given location is between 0 and limit, then * return that location; otherwise return the closest * valid location to the given location.

* *

This method is a helper method that does not change the * slider state.

* * @param loc the location to test */ public final int getValidLocation(int loc) { if (loc < 0) return 0; if (loc > limit) return limit; return loc; } /** *

The affine transform that converts the given value * to its best approximation as a location on the track.

* *

This method is a helper method that does not change the * slider state.

* * @param val the value to convert */ public final int valueToLocation(int val) { return (int) Math.round(f_val_to_loc * val + t_val_to_loc); } /** *

The affine transform that converts the given location * on the track to its best approximation as a value.

* *

This method is a helper method that does not change the * slider state.

* * @param loc the location to convert */ public final int locationToValue(int loc) { return (int) Math.round(f_loc_to_val * loc + t_loc_to_val); } /** Returns the current conceptual value of the slider. */ public final int getValue() { return value; } /** *

Sets the current conceptual value of the slider * in a manner that simulates what happens when the * slider is set interactively via the mouse.

* *

Uses the following steps:

* * * * @param val the value to set */ public final void setValue(int val) { pressActions.actionPerformed(pressEvent); setValueHelper(val); slidingActions.actionPerformed(slidingEvent); releaseActions.actionPerformed(releaseEvent); } /** *

Sets the current conceptual value of the slider * but does not invoke the press, sliding, or release * actions.

* *

Ensures that the value used is valid.

* *

Updates the corresponding track location * to the best approximation for this value.

* *

Calls resetThumb() and * updateValueTFV() to update the GUI.

* *

This method is normally not called directly since * it does not invoke the user defined actions. However, * to support unusual circumstances, it is available as * a public method.

* * @param val the value to set */ public final void setValueHelper(int val) { value = getValidValue(val); location = valueToLocation(value); resetThumb(); updateValueTFV(); } /** Returns the current track location of the slider. */ public final int getTrackLocation() { return location; } /** *

Sets the current track location of the slider * in a manner that simulates what happens when the * slider is set interactively via the mouse.

* *

Uses the following steps:

* * * * @param loc the location to set */ public final void setTrackLocation(int loc) { pressActions.actionPerformed(pressEvent); setTrackLocationHelper(loc); slidingActions.actionPerformed(slidingEvent); releaseActions.actionPerformed(releaseEvent); } /** *

Sets the current track location of the slider * but does not invoke the press, sliding, or release * actions.

* *

Ensures that the location used is valid.

* *

Updates the corresponding conceptual value * to the best approximation for this location.

* *

Calls resetThumb() and * updateValueTFV() to update the GUI.

* *

This method is normally not called directly since * it does not invoke the user defined actions. However, * to support unusual circumstances, it is available as * a public method.

* * @param loc the location to set */ public final void setTrackLocationHelper(int loc) { location = getValidLocation(loc); value = locationToValue(location); resetThumb(); updateValueTFV(); } /** *

The method to reset the location of the * slider thumb on the track.

*/ public final void resetThumb() { if (orientation == HORIZONTAL) { thumb.moveCenterTo(location, 0); } else { thumb.moveCenterTo(0, location); } } /** * Set the ordinary paint for the thumb. * * @param paint the paint to set */ public final void setOrdinaryThumbPaint(Paint paint) { if (paint == null) return; ordinaryThumbPaint = paint; if (!dragging) thumb.setFillPaint(paint); } /** * Set the selected paint for the thumb. * * @param paint the paint to set */ public final void setSelectedThumbPaint(Paint paint) { if (paint == null) return; selectedThumbPaint = paint; if (dragging) thumb.setFillPaint(paint); } /** * Set the paint for the track. * * @param paint the paint to set */ public final void setTrackPaint(Paint paint) { if (paint == null) return; trackPaint = paint; track.setFillPaint(paint); } /** * Set the common color of ticks, borders, and text labels. */ public final void setCommonColor(Color color) { if (color == null) return; commonColor = color; trackBorder.setFillPaint(color); int n = tickSequence.length(); for (int i = 0; i < n; i++) { Paintable paintable = tickSequence.getPaintable(i); if (paintable instanceof ShapePaintable) { ShapePaintable sp = (ShapePaintable) paintable; sp.setDrawPaint(color); } } n = labelSequence.length(); for (int i = 0; i < n; i++) { Paintable paintable = labelSequence.getPaintable(i); if (paintable instanceof TextPaintable) { TextPaintable tp = (TextPaintable) paintable; tp.setFillPaint(color); } } valueTFV.setForeground(commonColor); valueTFV.setSelectedTextColor(commonColor); } /** *

Adds the given action listener to the sequence of actions * that is performed when slider is pressed in its active area * (thumb or track).

* *

This action will be invoked with the standard event * pressEvent.

* *

This action may query this slider using the methods * getValue() or getTrackLocation() * to decide what to do.

* * @param a the press action listener to add */ public void addPressAction(ActionListener a) { pressActions.add(a); } /** *

Adds the given action listener to the sequence of actions * that is performed when slider is sliding after being pressed * in its active area (thumb or track).

* *

This action will be invoked with the standard event * slidingEvent.

* *

This action may query this slider using the methods * getValue() or getTrackLocation() * to decide what to do.

* * @param a the sliding action listener to add */ public void addSlidingAction(ActionListener a) { slidingActions.add(a); } /** *

Adds the given action listener to the sequence of actions * that is performed when slider is released after being pressed * in its active area (thumb or track).

* *

This action will be invoked with the standard event * releaseEvent.

* *

This action may query this slider using the methods * getValue() or getTrackLocation() * to decide what to do.

* * @param a the release action listener to add */ public void addReleaseAction(ActionListener a) { releaseActions.add(a); } /** * Removes the given action listener from the press actions. * * @param a the press action listener to remove */ public void removePressAction(ActionListener a) { pressActions.remove(a); } /** * Removes the given action listener from the sliding actions. * * @param a the sliding action listener to remove */ public void removeSlidingAction(ActionListener a) { slidingActions.remove(a); } /** * Removes the given action listener from the release actions. * * @param a the release action listener to remove */ public void removeReleaseAction(ActionListener a) { releaseActions.remove(a); } /** *

Sets the sequence of press actions.

* *

Clears the press actions if the parameter is * null.

* * @param sequence the new press actions */ public void setPressActions(ActionSequence sequence) { if (sequence == null) pressActions.clear(); else pressActions = sequence; } /** *

Sets the sequence of sliding actions.

* *

Clears the sliding actions if the parameter is * null.

* * @param sequence the new sliding actions */ public void setSlidingActions(ActionSequence sequence) { if (sequence == null) slidingActions.clear(); else slidingActions = sequence; } /** *

Sets the sequence of release actions.

* *

Clears the release actions if the parameter is * null.

* * @param sequence the new release actions */ public void setReleaseActions(ActionSequence sequence) { if (sequence == null) releaseActions.clear(); else releaseActions = sequence; } /** Returns the sequence of press actions. */ public ActionSequence getPressActions() { return pressActions; } /** Returns the sequence of sliding actions. */ public ActionSequence getSlidingActions() { return slidingActions; } /** Returns the sequence of release actions. */ public ActionSequence getReleaseActions() { return releaseActions; } /** *

This method computes the bounds of the sequence * mainSequence, stores those bounds in * mainBounds, and sets the corner data * cornerX and cornerY for * use in computation of mouse coordinates.

* *

This method also sets the default bounds of * mainSequence to the newly computed * mainBounds so that any further change * to the main sequence cannot affect its bounds.

* *

The purpose of this method is make computations * with the mouse efficient.

* *

This method will be called when the first mouse * interaction with the main component occurs. If it * is called again, it will do nothing.

*/ protected final void freezeBounds() { if (mainBounds != null) return; mainBounds = mainSequence.getBounds2D(); mainSequence.setDefaultBounds2D(mainBounds); cornerX = (int) Math.round(mainBounds.x); cornerY = (int) Math.round(mainBounds.y); } /** *

Sets mouseX and mouseY * by adjusting the mouse position in the given mouse * event by the corner coordinates.

* * @param evt the mouse event */ protected final void setMouseCoordinates(MouseEvent evt) { if (evt == null) return; mouseX = cornerX + evt.getX(); mouseY = cornerY + evt.getY(); } /** *

The method to update the value text field view * using the current value settings.

*/ protected final void updateValueTFV() { valueTFV.setViewState("" + value); } /** *

The method to update the value * using the contents of the value text field view.

* *

If the contents of the value text field view * causes a parse exception, the user will be given * a chance to correct the error or cancel. If the * contents is parsable as an integer, then it will * be used in a call to setValue. If * that call determines that the value is invalid * then the value set will be forced into range.

* *

This method implements the action of the same name * and the corresponding action is set as a listener for * the value text field view.

* *

If successful, this method will reset the thumb * and perform a press, sliding, release sequence * for the user-defined actions.

*/ protected final void setValueFromValueTFV() { try { int val = valueTFV.requestInt(); setValue(val); } catch (CancelledException ex) { updateValueTFV(); } } /** *

The mouse press behavior.

* *

If the mouse was pressed in the active area of the slider * (thumb or track), performs the standard startup behavior for * the mouse press:

* * * *

Before processing, calls freezeBounds * to ensure that the relation between * the event coordinates for the main component and * the mouse coordinates relative to the main sequence * is fixed once and for all.

*/ protected final void mousePress(MouseEvent evt) { freezeBounds(); setMouseCoordinates(evt); int index = mainSequence.hitsItemAtIndex(mouseX, mouseY); dragging = (index >= 0) && (index <= 2); if (dragging) { pressActions.actionPerformed(pressEvent); thumb.setFillPaint(selectedThumbPaint); if (orientation == HORIZONTAL) setTrackLocationHelper(mouseX); else setTrackLocationHelper(mouseY); } } /** *

The mouse sliding behavior.

* *

If the mouse was pressed in the active area of the slider * (thumb or track), performs the standard sliding behavior for * the subsequent mouse movement:

* * */ protected final void mouseSliding(MouseEvent evt) { if (dragging) { setMouseCoordinates(evt); if (orientation == HORIZONTAL) setTrackLocationHelper(mouseX); else setTrackLocationHelper(mouseY); slidingActions.actionPerformed(slidingEvent); } } /** *

The mouse release behavior.

* *

If the mouse was pressed in the active area of the slider * (thumb or track), performs the standard release behavior for * the subsequent mouse release:

* * */ protected final void mouseRelease(MouseEvent evt) { if (dragging) { thumb.setFillPaint(ordinaryThumbPaint); setMouseCoordinates(evt); if (orientation == HORIZONTAL) setTrackLocationHelper(mouseX); else setTrackLocationHelper(mouseY); setValueHelper(value); dragging = false; slidingActions.actionPerformed(slidingEvent); releaseActions.actionPerformed(releaseEvent); } } /////////////// // TypedView // /////////////// /** * Returns an XInt object * whose state is set to the value of this slider. */ public Stringable demandObject() { return new XInt(getValue()); } /** * Returns an XInt object * whose state is set to the value of this slider. */ public Stringable requestObject() { return demandObject(); } public void setInputProperties(InputProperties p) { if (p == null) p = InputProperties.BASE_PROPERTIES; properties = p; } public InputProperties getInputProperties() { return properties; } /** Returns the XInt class object. */ public Class getDataType() { return XInt.class; } ///////////////// // Displayable // ///////////////// /** *

Sets the value for this slider * to the int value represented * by the given String data.

* *

If the String is not parsable to * an int, then this method does * nothing.

* *

If the String is parsable to an * int but that int is not * in range then the value will be forced into range.

* * @param data the new view state */ public void setViewState(String data) { try { XInt x = new XInt(data); setValue(x.getValue()); } catch (ParseException ex) { } } /** * Returns a String representation * of the current integer value of this slider. */ public String getViewState() { return "" + value; } /** *

Sets the default value for this slider * to the int value represented * by the given String data.

* *

If the String is not parsable to * an int, then this method does * nothing.

* *

If the String is parsable to an * int but that int is not * in range then the value will be forced into range.

* * @param data the new default view state */ public void setDefaultViewState(String data) { try { XInt x = new XInt(data); defaultValue = getValidValue(x.getValue()); } catch (ParseException ex) { } } /** * Returns a String representation * of the default integer value of this slider. */ public String getDefaultViewState() { return "" + defaultValue; } /** Resets the slider to its default value. */ public void reset() { setValue(defaultValue); } /** * Returns a String representation * of the current integer value of this slider. */ public String toString() { return "" + value; } }