This commit was manufactured by cvs2svn to create branch
[official-gcc.git] / libjava / javax / swing / JSlider.java
blob0bc013cb128a79c88d98b8ba7e8b6bf3722ef001
1 /* JSlider.java --
2 Copyright (C) 2002, 2004 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
9 any later version.
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
19 02111-1307 USA.
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
24 combination.
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
38 package javax.swing;
40 import java.awt.Dimension;
41 import java.awt.MenuContainer;
42 import java.awt.image.ImageObserver;
43 import java.io.Serializable;
44 import java.util.Dictionary;
45 import java.util.Enumeration;
46 import java.util.Hashtable;
48 import javax.accessibility.Accessible;
49 import javax.accessibility.AccessibleContext;
50 import javax.accessibility.AccessibleRole;
51 import javax.accessibility.AccessibleStateSet;
52 import javax.accessibility.AccessibleValue;
53 import javax.swing.event.ChangeEvent;
54 import javax.swing.event.ChangeListener;
55 import javax.swing.plaf.SliderUI;
58 /**
59 * <p>
60 * The JSlider is a Swing component that allows selection of a value within a
61 * range by adjusting a thumb in a track. The values for the minimum,
62 * maximum, extent and value are stored in a {@link
63 * DefaultBoundedRangeModel}.
64 * </p>
66 * <p>
67 * JSliders have the following properties:
68 * </p>
70 * <table>
71 * <tr><th> Property </th><th> Stored in </th><th> Bound? </th></tr>
72 * <tr><td> extent </td><td> model </td><td> no </td></tr>
73 * <tr><td> inverted </td><td> slider </td><td> yes </td></tr>
74 * <tr><td> labelTable </td><td> slider </td><td> yes </td></tr>
75 * <tr><td> majorTickSpacing </td><td> slider </td><td> yes </td></tr>
76 * <tr><td> maximum </td><td> model </td><td> no </td></tr>
77 * <tr><td> minimum </td><td> model </td><td> no </td></tr>
78 * <tr><td> minorTickSpacing </td><td> slider </td><td> yes </td></tr>
79 * <tr><td> model </td><td> slider </td><td> yes </td></tr>
80 * <tr><td> orientation </td><td> slider </td><td> yes </td></tr>
81 * <tr><td> paintLabels </td><td> slider </td><td> yes </td></tr>
82 * <tr><td> paintTicks </td><td> slider </td><td> yes </td></tr>
83 * <tr><td> snapToTicks </td><td> slider </td><td> no </td></tr>
84 * <tr><td> value </td><td> model </td><td> no </td></tr>
85 * <tr><td> valueIsAdjusting </td><td> model </td><td> no </td></tr>
86 * </table>
88 * <p>
89 * The various behavioral aspects of these properties follows:
90 * </p>
92 * <ul>
93 * <li>
94 * When non-bound properties stored in the slider change, the slider fires
95 * ChangeEvents to its ChangeListeners.
96 * </li>
97 * <li>
98 * When bound properties stored in the slider change, the slider fires
99 * PropertyChangeEvents to its PropertyChangeListeners
100 * </li>
101 * <li>
102 * If any of the model's properties change, it fires a ChangeEvent to its
103 * ChangeListeners, which include the slider.
104 * </li>
105 * <li>
106 * If the slider receives a ChangeEvent from its model, it will propagate the
107 * ChangeEvent to its ChangeListeners, with the ChangeEvent's "source"
108 * property set to refer to the slider, rather than the model.
109 * </li>
110 * </ul>
112 public class JSlider extends JComponent implements SwingConstants, Accessible,
113 ImageObserver,
114 MenuContainer, Serializable
116 /** DOCUMENT ME! */
117 static final long serialVersionUID = -1441275936141218479L;
120 * DOCUMENT ME!
122 protected class AccessibleJSlider extends JComponent.AccessibleJComponent
123 implements AccessibleValue
125 private static final long serialVersionUID = -6301740148041106789L;
128 * Creates a new AccessibleJSlider object.
130 * @param value0 DOCUMENT ME!
132 protected AccessibleJSlider()
137 * DOCUMENT ME!
139 * @return DOCUMENT ME!
141 public AccessibleStateSet getAccessibleStateSet()
143 return null;
147 * DOCUMENT ME!
149 * @return DOCUMENT ME!
151 public AccessibleRole getAccessibleRole()
153 return null;
157 * DOCUMENT ME!
159 * @return DOCUMENT ME!
161 public AccessibleValue getAccessibleValue()
163 return null;
167 * DOCUMENT ME!
169 * @return DOCUMENT ME!
171 public Number getCurrentAccessibleValue()
173 return null;
177 * setCurrentAccessibleValue
179 * @param value0 TODO
181 * @return boolean
183 public boolean setCurrentAccessibleValue(Number value0)
185 return false;
189 * getMinimumAccessibleValue
191 * @return Number
193 public Number getMinimumAccessibleValue()
195 return null;
199 * getMaximumAccessibleValue
201 * @return Number
203 public Number getMaximumAccessibleValue()
205 return null;
209 /** Fired in a PropertyChangeEvent when the "inverted" property changes. */
210 public static final String INVERTED_CHANGED_PROPERTY = "inverted";
212 /** Fired in a PropertyChangeEvent when the "labelTable" property changes. */
213 public static final String LABEL_TABLE_CHANGED_PROPERTY = "labelTable";
216 * Fired in a PropertyChangeEvent when the "majorTickSpacing" property
217 * changes.
219 public static final String MAJOR_TICK_SPACING_CHANGED_PROPERTY = "majorTickSpacing";
222 * Fired in a PropertyChangeEvent when the "minorTickSpacing" property
223 * changes.
225 public static final String MINOR_TICK_SPACING_CHANGED_PROPERTY = "minorTickSpacing";
227 /** Fired in a PropertyChangeEvent when the "model" property changes. */
228 public static final String MODEL_CHANGED_PROPERTY = "model";
230 /** Fired in a PropertyChangeEvent when the "orientation" property changes. */
231 public static final String ORIENTATION_CHANGED_PROPERTY = "orientation";
233 /** Fired in a PropertyChangeEvent when the "paintLabels" property changes. */
234 public static final String PAINT_LABELS_CHANGED_PROPERTY = "paintLabels";
236 /** Fired in a PropertyChangeEvent when the "paintTicks" property changes. */
237 public static final String PAINT_TICKS_CHANGED_PROPERTY = "paintTicks";
239 /** Whether or not this slider paints its ticks. */
240 private transient boolean paintTicks = false;
242 /** Whether or not this slider paints its track. */
243 private transient boolean paintTrack = true;
245 /** Whether or not this slider paints its labels. */
246 private transient boolean paintLabels = false;
249 * A dictionary of (Integer, Component) pairs where each Component is a
250 * JLabel and the Integer determines where the label will be painted.
252 private transient Dictionary labelTable;
254 /** The model used to describe the slider. */
255 protected BoundedRangeModel sliderModel;
257 /** The space between major ticks. */
258 protected int majorTickSpacing;
260 /** The space between minor ticks. */
261 protected int minorTickSpacing;
263 /** Whether the slider snaps its values to ticks. */
264 protected boolean snapToTicks = true;
266 /** The orientation of the slider. */
267 protected int orientation = HORIZONTAL;
269 /** Whether the slider is inverted. */
270 private transient boolean isInverted;
272 /** The ChangeListener that listens to the model. */
273 protected ChangeListener changeListener;
275 /** The ChangeEvent that is passed to all listeners of this slider. */
276 protected transient ChangeEvent changeEvent;
279 * Creates a new horizontal JSlider object with a minimum of 0, a maximum of
280 * 100, and a value of 50.
282 public JSlider()
284 this(HORIZONTAL, 0, 100, 50);
288 * Creates a new JSlider object with the given orientation and a minimum of
289 * 0, a maximum of 100, and a value of 50.
291 * @param orientation The orientation of the slider.
293 public JSlider(int orientation)
295 this(orientation, 0, 100, 50);
299 * Creates a new horizontal JSlider object with the given maximum and
300 * minimum and a value that is halfway between the minimum and the
301 * maximum.
303 * @param minimum The minimum value of the JSlider.
304 * @param maximum The maximum value of the JSlider.
306 public JSlider(int minimum, int maximum)
308 this(HORIZONTAL, minimum, maximum, (maximum + minimum) / 2);
312 * Creates a new horizontal JSlider object with the given minimum, maximum,
313 * and value.
315 * @param minimum The minimum value of the JSlider.
316 * @param maximum The maximum value of the JSlider.
317 * @param value The initial value of the JSlider.
319 public JSlider(int minimum, int maximum, int value)
321 this(HORIZONTAL, minimum, maximum, value);
325 * Creates a new JSlider object with the given orientation, minimum,
326 * maximum, and value.
328 * @param orientation The orientation of the JSlider.
329 * @param minimum The minimum value of the JSlider.
330 * @param maximum The maximum value of the JSlider.
331 * @param value The initial value of the JSlider.
333 public JSlider(int orientation, int minimum, int maximum, int value)
335 sliderModel = new DefaultBoundedRangeModel(value, 0, minimum, maximum);
336 if (orientation != HORIZONTAL && orientation != VERTICAL)
337 throw new IllegalArgumentException(orientation + " is not a legal orientation");
338 this.orientation = orientation;
339 changeListener = createChangeListener();
340 sliderModel.addChangeListener(changeListener);
341 updateUI();
345 * Creates a new horizontal JSlider object with the given model.
347 * @param model The model the slider will be created with.
349 public JSlider(BoundedRangeModel model)
351 if (model == null)
352 sliderModel = new DefaultBoundedRangeModel(50, 0, 0, 100);
353 else
354 sliderModel = model;
355 changeListener = createChangeListener();
356 sliderModel.addChangeListener(changeListener);
357 updateUI();
361 * This method returns the current value of the slider.
363 * @return The value of the slider stored in the model.
365 public int getValue()
367 return sliderModel.getValue();
371 * This method sets the value of the slider.
373 * @param value The slider's new value.
375 public void setValue(int value)
377 sliderModel.setValue(value);
381 * This method returns the slider's UI delegate.
383 * @return The slider's UI delegate.
385 public SliderUI getUI()
387 return (SliderUI) ui;
391 * This method sets the slider's UI delegate.
393 * @param ui A SliderUI object to use with this slider.
395 public void setUI(SliderUI ui)
397 super.setUI(ui);
401 * This method sets this slider's UI to the UIManager's default for the
402 * current look and feel.
404 public void updateUI()
406 setUI((SliderUI) UIManager.getUI(this));
407 invalidate();
408 repaint();
412 * This method returns a name to identify which look and feel class will be
413 * the UI delegate for the slider.
415 * @return The Look and Feel classID. "SliderUI"
417 public String getUIClassID()
419 return "SliderUI";
423 * Creates a ChangeListener for this Slider.
425 * @return A new ChangeListener.
427 protected ChangeListener createChangeListener()
429 return new ChangeListener()
431 public void stateChanged(ChangeEvent ce)
433 // No need to trigger a repaint since the UI listens to the model
434 // as well. All we need to do is pass on the stateChanged event
435 // to our listeners.
436 fireStateChanged();
442 * This method registers a listener to this slider. The listener will be
443 * informed of new ChangeEvents.
445 * @param listener The listener to register.
447 public void addChangeListener(ChangeListener listener)
449 listenerList.add(ChangeListener.class, listener);
453 * This method removes a listener from this slider.
455 * @param listener The listener to remove.
457 public void removeChangeListener(ChangeListener listener)
459 listenerList.remove(ChangeListener.class, listener);
463 * This method is called whenever the model fires a ChangeEvent. It should
464 * propagate the ChangeEvent to its listeners with a new ChangeEvent that
465 * identifies the slider as the source.
467 protected void fireStateChanged()
469 Object[] changeListeners = listenerList.getListenerList();
470 if (changeEvent == null)
471 changeEvent = new ChangeEvent(this);
472 for (int i = changeListeners.length - 2; i >= 0; i -= 2)
474 if (changeListeners[i] == ChangeListener.class)
475 ((ChangeListener) changeListeners[i + 1]).stateChanged(changeEvent);
480 * This method returns an array of all ChangeListeners listening to this
481 * slider.
483 * @return An array of ChangeListeners listening to this slider.
485 public ChangeListener[] getChangeListeners()
487 return (ChangeListener[]) listenerList.getListeners(ChangeListener.class);
491 * This method returns the model of the slider.
493 * @return The slider's model.
495 public BoundedRangeModel getModel()
497 return sliderModel;
501 * This method changes the "model" property. It also needs to unregister
502 * any listeners to the old model and register any listeners to the new
503 * model.
505 * @param model The model to use with the slider.
507 public void setModel(BoundedRangeModel model)
509 // I didn't do the null pointer check on purpose.
510 // If you try it with Sun's, it'll go ahead and set it to null
511 // and bork the next time it tries to access the model.
512 if (model != sliderModel)
514 BoundedRangeModel oldModel = sliderModel;
515 sliderModel = model;
516 oldModel.removeChangeListener(changeListener);
517 sliderModel.addChangeListener(changeListener);
518 firePropertyChange(MODEL_CHANGED_PROPERTY, oldModel, sliderModel);
523 * This method returns the minimum value of the slider.
525 * @return The minimum value of the slider.
527 public int getMinimum()
529 return sliderModel.getMinimum();
533 * This method sets the minimum value of the slider.
535 * @param minimum The minimum value of the slider.
537 public void setMinimum(int minimum)
539 sliderModel.setMinimum(minimum);
543 * This method returns the maximum value of the slider.
545 * @return The maximum value of the slider.
547 public int getMaximum()
549 return sliderModel.getMaximum();
553 * This method sets the maximum value of the slider.
555 * @param maximum The maximum value of the slider.
557 public void setMaximum(int maximum)
559 sliderModel.setMaximum(maximum);
563 * This method returns this slider's isAdjusting value which is true if the
564 * thumb is being dragged.
566 * @return The slider's isAdjusting value.
568 public boolean getValueIsAdjusting()
570 return sliderModel.getValueIsAdjusting();
574 * This method sets the isAdjusting value for the slider.
576 * @param adjusting The slider's isAdjusting value.
578 public void setValueIsAdjusting(boolean adjusting)
580 sliderModel.setValueIsAdjusting(adjusting);
584 * This method returns the extent value for this slider.
586 * @return The extent value for this slider.
588 public int getExtent()
590 return sliderModel.getExtent();
594 * This method sets the extent value for this slider.
596 * @param extent The extent value for this slider.
598 public void setExtent(int extent)
600 sliderModel.setExtent(extent);
604 * This method returns the slider orientation.
606 * @return The orientation of the slider.
608 public int getOrientation()
610 return orientation;
614 * This method changes the "orientation" property of this slider. If the
615 * orientation is not VERTICAL or HORIZONTAL, this method does nothing.
617 * @param orientation The orientation of this slider.
619 public void setOrientation(int orientation)
621 if (orientation != VERTICAL && orientation != HORIZONTAL)
622 throw new IllegalArgumentException("orientation must be one of: VERTICAL, HORIZONTAL");
623 if (orientation != this.orientation)
625 int oldOrientation = this.orientation;
626 this.orientation = orientation;
627 firePropertyChange(ORIENTATION_CHANGED_PROPERTY, oldOrientation,
628 this.orientation);
633 * This method returns the label table for this slider.
635 * @return The label table for this slider.
637 public Dictionary getLabelTable()
639 return labelTable;
643 * This method changes the "labelTable" property of this slider.
645 * @param table The label table for this slider.
647 public void setLabelTable(Dictionary table)
649 if (table != labelTable)
651 Dictionary oldTable = labelTable;
652 labelTable = table;
653 firePropertyChange(LABEL_TABLE_CHANGED_PROPERTY, oldTable, labelTable);
658 * This method is called to reset UI delegates for the labels in the
659 * labelTable to a default for the current look and feel.
661 protected void updateLabelUIs()
663 if (labelTable == null)
664 return;
665 for (Enumeration list = labelTable.elements(); list.hasMoreElements();)
667 JLabel label = (JLabel) list.nextElement();
668 label.updateUI();
673 * Creates a hashtable of (Integer, JLabel) pairs that can be used as a
674 * label table for this slider. The labels will start from the sliders
675 * minimum and increase by the increment. Each label will have a text
676 * string indicating their integer value.
678 * @param increment The increment to between labels.
680 * @return A hashtable with the labels and their keys.
682 public Hashtable createStandardLabels(int increment)
684 return createStandardLabels(increment, sliderModel.getMinimum());
688 * Creates a hashtable of (Integer, JLabel) pairs that can be used as a
689 * label table for this slider. The labels will start from the given start
690 * value and increase by the increment. Each label will have a text string
691 * indicating their integer value.
693 * @param increment The increment to between labels.
694 * @param start The value to start from.
696 * @return A hashtable with the labels and their keys.
698 public Hashtable createStandardLabels(int increment, int start)
700 Hashtable table = new Hashtable();
701 JLabel label;
702 Dimension dim;
704 int max = sliderModel.getMaximum();
706 for (int i = start; i <= max; i += increment)
708 label = new JLabel(String.valueOf(i));
709 label.setVerticalAlignment(CENTER);
710 label.setHorizontalAlignment(CENTER);
712 // Make sure these labels have the width and height
713 // they want.
714 dim = label.getPreferredSize();
715 label.setBounds(label.getX(), label.getY(),
716 (int) dim.getWidth(),
717 (int) dim.getHeight());
718 table.put(new Integer(i), label);
720 return table;
724 * This method returns whether the slider is inverted. Horizontal sliders
725 * that are not inverted will have the minimums on the left. If they are
726 * inverted, the minimums will be on the right. Vertical sliders that are
727 * not inverted will have the minimums at the bottom. If they are inverted,
728 * the minimums will be at the top.
730 * @return Whether this slider is inverted.
732 public boolean getInverted()
734 return isInverted;
738 * This method changes the "inverted" property for this slider.Horizontal
739 * sliders that are not inverted will have the minimums on the left. If
740 * they are inverted, the minimums will be on the right. Vertical sliders
741 * that are not inverted will have the minimums at the bottom. If they are
742 * inverted, the minimums will be at the top. However, if the slider's
743 * componentOrientation is set to RIGHT_TO_LEFT, then everything gets
744 * reversed again.
746 * @param inverted Whether the slider should be inverted.
748 public void setInverted(boolean inverted)
750 if (isInverted != inverted)
752 boolean oldInverted = isInverted;
753 isInverted = inverted;
754 firePropertyChange(INVERTED_CHANGED_PROPERTY, oldInverted, isInverted);
759 * This method returns the amount of units between each major tick mark.
761 * @return The amount of units between each major tick mark.
763 public int getMajorTickSpacing()
765 return majorTickSpacing;
769 * This method changes the "majorTickSpacing" property for this slider. The
770 * major tick spacing is the amount of units between each major tick mark.
772 * @param spacing The amount of units between each major tick mark.
774 public void setMajorTickSpacing(int spacing)
776 if (majorTickSpacing != spacing)
778 int oldSpacing = majorTickSpacing;
779 majorTickSpacing = spacing;
780 firePropertyChange(MAJOR_TICK_SPACING_CHANGED_PROPERTY, oldSpacing,
781 majorTickSpacing);
786 * This method returns the amount of units between each minor tick mark.
788 * @return The amount of units between each minor tick mark.
790 public int getMinorTickSpacing()
792 return minorTickSpacing;
796 * This method changes the "minorTickSpacing" property for this slider. The
797 * minor tick spacing is the amount of units between each minor tick mark.
799 * @param spacing The amount of units between each minor tick mark.
801 public void setMinorTickSpacing(int spacing)
803 if (minorTickSpacing != spacing)
805 int oldSpacing = minorTickSpacing;
806 minorTickSpacing = spacing;
807 firePropertyChange(MINOR_TICK_SPACING_CHANGED_PROPERTY, oldSpacing,
808 minorTickSpacing);
813 * This method returns whether this slider is snapping to ticks. Sliders
814 * that snap to ticks will automatically move the thumb to the nearest tick
815 * mark.
817 * @return Whether this slider snaps to ticks.
819 public boolean getSnapToTicks()
821 return snapToTicks;
825 * This method sets whether this slider will snap to ticks. Sliders that
826 * snap to ticks will automatically move the thumb to the nearest tick
827 * mark.
829 * @param snap Whether this slider snaps to ticks.
831 public void setSnapToTicks(boolean snap)
833 if (snap != snapToTicks)
835 snapToTicks = snap;
836 fireStateChanged();
841 * This method returns whether the slider will paint its tick marks. In
842 * addition to setting this property to true, one of minor tick spacing or
843 * major tick spacing must be set to a value greater than 0 in order for
844 * ticks to be painted.
846 * @return Whether ticks will be painted.
848 public boolean getPaintTicks()
850 return paintTicks;
854 * This method changes the "paintTicks" property for this slider. In
855 * addition to setting this property to true, one of minor tick spacing or
856 * major tick spacing must be set to a value greater than 0 in order for
857 * ticks to be painted.
859 * @param paint Whether ticks will be painted.
861 public void setPaintTicks(boolean paint)
863 if (paint != paintTicks)
865 boolean oldPaintTicks = paintTicks;
866 paintTicks = paint;
867 firePropertyChange(PAINT_TICKS_CHANGED_PROPERTY, oldPaintTicks,
868 paintTicks);
873 * This method returns whether the track will be painted.
875 * @return Whether the track will be painted.
877 public boolean getPaintTrack()
879 return paintTrack;
883 * This method sets whether the track will be painted.
885 * @param paint Whether the track will be painted.
887 public void setPaintTrack(boolean paint)
889 paintTrack = paint;
893 * This method returns whether labels will be painted.
895 * @return Whether labels will be painted.
897 public boolean getPaintLabels()
899 return paintLabels;
903 * This method changes the "paintLabels" property.
905 * @param paint Whether labels will be painted.
907 public void setPaintLabels(boolean paint)
909 if (paint != paintLabels)
911 boolean oldPaintLabels = paintLabels;
912 paintLabels = paint;
913 firePropertyChange(PAINT_LABELS_CHANGED_PROPERTY, oldPaintLabels,
914 paintLabels);
919 * This method is used primarily for debugging purposes and returns a string
920 * that can be used to represent this slider.
922 * @return A string representing this slider.
924 protected String paramString()
926 return "JSlider";
930 * DOCUMENT ME!
932 * @return DOCUMENT ME!
934 public AccessibleContext getAccessibleContext()
936 if (accessibleContext == null)
937 accessibleContext = new AccessibleJSlider();
939 return accessibleContext;