JSlider.java revision 345
2362N/A * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 0N/A * published by the Free Software Foundation. Sun designates this 0N/A * particular file as subject to the "Classpath" exception as provided 0N/A * by Sun in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 2362N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 0N/A * CA 95054 USA or visit www.sun.com if you need additional information or 0N/A * have any questions. 0N/A * A component that lets the user graphically select a value by sliding 0N/A * a knob within a bounded interval. 0N/A * The slider can show both 0N/A * major tick marks, and minor tick marks between the major ones. The number of 0N/A * values between the tick marks is controlled with 0N/A * <code>setMajorTickSpacing</code> and <code>setMinorTickSpacing</code>. 0N/A * Painting of tick marks is controlled by {@code setPaintTicks}. 0N/A * Sliders can also print text labels at regular intervals (or at 0N/A * arbitrary locations) along the slider track. Painting of labels is 0N/A * controlled by {@code setLabelTable} and {@code setPaintLabels}. 0N/A * For further information and examples see * a section in <em>The Java Tutorial.</em> * <strong>Warning:</strong> Swing is not thread safe. For more * <strong>Warning:</strong> * Serialized objects of this class will not be compatible with * future Swing releases. The current serialization support is * appropriate for short term storage or RMI between applications running * the same version of Swing. As of 1.4, support for long term storage * of all JavaBeans<sup><font size="-2">TM</font></sup> * has been added to the <code>java.beans</code> package. * attribute: isContainer false * description: A component that supports selecting a integer value from a range. * The data model that handles the numeric maximum value, * minimum value, and current-position value for the slider. * The number of values between the major tick marks -- the * larger marks that break up the minor tick marks. * The number of values between the minor tick marks -- the * smaller marks that occur between the major tick marks. * @see #setMinorTickSpacing * If true, the knob (and the data value it represents) * resolve to the closest tick mark next to where the user * positioned the knob. The default is false. * If true, the knob (and the data value it represents) * resolve to the closest slider value next to where the user * Whether the slider is horizontal or vertical * The default is horizontal. * {@code Dictionary} of what labels to draw at which values * The changeListener (no suffix) is the listener we add to the * slider's model. This listener is initialized to the * {@code ChangeListener} returned from {@code createChangeListener}, * which by default just forwards events * to {@code ChangeListener}s (if any) added directly to the slider. * @see #addChangeListener * @see #createChangeListener * Only one <code>ChangeEvent</code> is needed per slider instance since the * event's only (read-only) state is the source property. The source * of events generated here is always "this". The event is lazily * created the first time that an event notification is fired. * Creates a horizontal slider with the range 0 to 100 and * an initial value of 50. * Creates a slider using the specified orientation with the * range {@code 0} to {@code 100} and an initial value of {@code 50}. * either <code>SwingConstants.VERTICAL</code> or * <code>SwingConstants.HORIZONTAL</code>. * @param orientation the orientation of the slider * @throws IllegalArgumentException if orientation is not one of {@code VERTICAL}, {@code HORIZONTAL} * Creates a horizontal slider using the specified min and max * with an initial value equal to the average of the min plus max. * The <code>BoundedRangeModel</code> that holds the slider's data * handles any issues that may arise from improperly setting the * minimum and maximum values on the slider. See the * {@code BoundedRangeModel} documentation for details. * @param min the minimum value of the slider * @param max the maximum value of the slider * Creates a horizontal slider using the specified min, max and value. * The <code>BoundedRangeModel</code> that holds the slider's data * handles any issues that may arise from improperly setting the * minimum, initial, and maximum values on the slider. See the * {@code BoundedRangeModel} documentation for details. * @param min the minimum value of the slider * @param max the maximum value of the slider * @param value the initial value of the slider * Creates a slider with the specified orientation and the * specified minimum, maximum, and initial values. * either <code>SwingConstants.VERTICAL</code> or * <code>SwingConstants.HORIZONTAL</code>. * The <code>BoundedRangeModel</code> that holds the slider's data * handles any issues that may arise from improperly setting the * minimum, initial, and maximum values on the slider. See the * {@code BoundedRangeModel} documentation for details. * @param orientation the orientation of the slider * @param min the minimum value of the slider * @param max the maximum value of the slider * @param value the initial value of the slider * @throws IllegalArgumentException if orientation is not one of {@code VERTICAL}, {@code HORIZONTAL} * Creates a horizontal slider using the specified * Gets the UI object which implements the L&F for this component. * @return the SliderUI object that implements the Slider L&F * Sets the UI object which implements the L&F for this component. * @param ui the SliderUI L&F object * attribute: visualUpdate true * description: The UI object that implements the slider's LookAndFeel. * Resets the UI property to a value from the current look and feel. * @see JComponent#updateUI // The labels preferred size may be derived from the font // of the slider, so we must update the UI of the slider first, then // that of labels. This way when setSize is called the right * Returns the name of the L&F class that renders this component. * @see JComponent#getUIClassID * We pass Change events along to the listeners with the * the slider (instead of the model itself) as the event source. * Subclasses that want to handle {@code ChangeEvent}s * from the model differently * can override this to return * an instance of a custom <code>ChangeListener</code> implementation. * The default {@code ChangeListener} simply calls the * {@code fireStateChanged} method to forward {@code ChangeEvent}s * to the {@code ChangeListener}s that have been added directly to the * @see javax.swing.event.ChangeListener * @see javax.swing.BoundedRangeModel * Adds a ChangeListener to the slider. * @param l the ChangeListener to add * @see #removeChangeListener * Removes a ChangeListener from the slider. * @param l the ChangeListener to remove * @see #addChangeListener * Returns an array of all the <code>ChangeListener</code>s added * to this JSlider with addChangeListener(). * @return all of the <code>ChangeListener</code>s added or an empty * array if no listeners have been added * Send a {@code ChangeEvent}, whose source is this {@code JSlider}, to * all {@code ChangeListener}s that have registered interest in * This method is called each time a {@code ChangeEvent} is received from * The event instance is created if necessary, and stored in * @see #addChangeListener * Returns the {@code BoundedRangeModel} that handles the slider's three * fundamental properties: minimum, maximum, value. * @return the data model for this component * Sets the {@code BoundedRangeModel} that handles the slider's three * fundamental properties: minimum, maximum, value. * Attempts to pass a {@code null} model to this method result in * undefined behavior, and, most likely, exceptions. * @param newModel the new, {@code non-null} <code>BoundedRangeModel</code> to use * description: The sliders BoundedRangeModel. * Returns the slider's current value * from the {@code BoundedRangeModel}. * @return the current value of the slider * @see BoundedRangeModel#getValue * Sets the slider's current value to {@code n}. This method * forwards the new value to the model. * The data model (an instance of {@code BoundedRangeModel}) * handles any mathematical * issues arising from assigning faulty values. See the * {@code BoundedRangeModel} documentation for details. * If the new value is different from the previous value, * all change listeners are notified. * @see #addChangeListener * @see BoundedRangeModel#setValue * description: The sliders current value. * Returns the minimum value supported by the slider * from the <code>BoundedRangeModel</code>. * @return the value of the model's minimum property * @see BoundedRangeModel#getMinimum * Sets the slider's minimum value to {@code minimum}. This method * forwards the new minimum value to the model. * The data model (an instance of {@code BoundedRangeModel}) * handles any mathematical * issues arising from assigning faulty values. See the * {@code BoundedRangeModel} documentation for details. * If the new minimum value is different from the previous minimum value, * all change listeners are notified. * @param minimum the new minimum * @see #addChangeListener * @see BoundedRangeModel#setMinimum * description: The sliders minimum value. * Returns the maximum value supported by the slider * from the <code>BoundedRangeModel</code>. * @return the value of the model's maximum property * @see BoundedRangeModel#getMaximum * Sets the slider's maximum value to {@code maximum}. This method * forwards the new maximum value to the model. * The data model (an instance of {@code BoundedRangeModel}) * handles any mathematical * issues arising from assigning faulty values. See the * {@code BoundedRangeModel} documentation for details. * If the new maximum value is different from the previous maximum value, * all change listeners are notified. * @param maximum the new maximum * @see #addChangeListener * @see BoundedRangeModel#setMaximum * description: The sliders maximum value. * Returns the {@code valueIsAdjusting} property from the model. For * details on how this is used, see the {@code setValueIsAdjusting} * @return the value of the model's {@code valueIsAdjusting} property * @see #setValueIsAdjusting * Sets the model's {@code valueIsAdjusting} property. Slider look and * feel implementations should set this property to {@code true} when * a knob drag begins, and to {@code false} when the drag ends. * @param b the new value for the {@code valueIsAdjusting} property * @see #getValueIsAdjusting * @see BoundedRangeModel#setValueIsAdjusting * description: True if the slider knob is being dragged. * Returns the "extent" from the <code>BoundedRangeModel</code>. * This respresents the range of values "covered" by the knob. * @return an int representing the extent * @see BoundedRangeModel#getExtent * Sets the size of the range "covered" by the knob. Most look * and feel implementations will change the value by this amount * if the user clicks on either side of the knob. This method just * forwards the new extent value to the model. * The data model (an instance of {@code BoundedRangeModel}) * handles any mathematical * issues arising from assigning faulty values. See the * {@code BoundedRangeModel} documentation for details. * If the new extent value is different from the previous extent value, * all change listeners are notified. * @param extent the new extent * @see BoundedRangeModel#setExtent * description: Size of the range covered by the knob. * Return this slider's vertical or horizontal orientation. * @return {@code SwingConstants.VERTICAL} or * {@code SwingConstants.HORIZONTAL} * Set the slider's orientation to either {@code SwingConstants.VERTICAL} or * {@code SwingConstants.HORIZONTAL}. * @param orientation {@code HORIZONTAL} or {@code VERTICAL} * @throws IllegalArgumentException if orientation is not one of {@code VERTICAL}, {@code HORIZONTAL} * attribute: visualUpdate true * description: Set the scrollbars orientation to either VERTICAL or HORIZONTAL. * enum: VERTICAL JSlider.VERTICAL * HORIZONTAL JSlider.HORIZONTAL // Check that there is a label with such image * Returns the dictionary of what labels to draw at which values. * @return the <code>Dictionary</code> containing labels and if ( labelTable == null && getMajorTickSpacing() > 0 ) { setLabelTable( createStandardLabels( getMajorTickSpacing() ) ); * Used to specify what label will be drawn at any given value. * The key-value pairs are of this format: * <code>{ Integer value, java.swing.JComponent label }</code>. * An easy way to generate a standard table of value labels is by using the * {@code createStandardLabels} method. * Once the labels have been set, this method calls {@link #updateLabelUIs}. * Note that the labels are only painted if the {@code paintLabels} * property is {@code true}. * @param labels new {@code Dictionary} of labels, or {@code null} to * @see #createStandardLabels(int) * attribute: visualUpdate true * description: Specifies what labels will be drawn for any given value. * Updates the UIs for the labels in the label table by calling * {@code updateUI} on each label. The UIs are updated from * the current look and feel. The labels are also set to their * @see JComponent#updateUI * Creates a {@code Hashtable} of numerical text labels, starting at the * slider minimum, and using the increment specified. * For example, if you call <code>createStandardLabels( 10 )</code> * and the slider minimum is zero, * then labels will be created for the values 0, 10, 20, 30, and so on. * For the labels to be drawn on the slider, the returned {@code Hashtable} * must be passed into {@code setLabelTable}, and {@code setPaintLabels} * must be set to {@code true}. * For further details on the makeup of the returned {@code Hashtable}, see * the {@code setLabelTable} documentation. * @param increment distance between labels in the generated hashtable * @return a new {@code Hashtable} of labels * @throws IllegalArgumentException if {@code increment} is less than or * Creates a {@code Hashtable} of numerical text labels, starting at the * starting point specified, and using the increment specified. * For example, if you call * <code>createStandardLabels( 10, 2 )</code>, * then labels will be created for the values 2, 12, 22, 32, and so on. * For the labels to be drawn on the slider, the returned {@code Hashtable} * must be passed into {@code setLabelTable}, and {@code setPaintLabels} * must be set to {@code true}. * For further details on the makeup of the returned {@code Hashtable}, see * the {@code setLabelTable} documentation. * @param increment distance between labels in the generated hashtable * @param start value at which the labels will begin * @return a new {@code Hashtable} of labels * @exception IllegalArgumentException if {@code start} is * out of range, or if {@code increment} is less than or equal // Save the labels that were added by the developer * Returns true if the value-range shown for the slider is reversed, * @return true if the slider values are reversed from their normal order * Specify true to reverse the value-range shown for the slider and false to * put the value range in the normal order. The order depends on the * slider's <code>ComponentOrientation</code> property. Normal (non-inverted) * horizontal sliders with a <code>ComponentOrientation</code> value of * <code>LEFT_TO_RIGHT</code> have their maximum on the right. * Normal horizontal sliders with a <code>ComponentOrientation</code> value of * <code>RIGHT_TO_LEFT</code> have their maximum on the left. Normal vertical * sliders have their maximum on the top. These labels are reversed when the * By default, the value of this property is {@code false}. * @param b true to reverse the slider values from their normal order * attribute: visualUpdate true * description: If true reverses the slider values from their normal order * This method returns the major tick spacing. The number that is returned * represents the distance, measured in values, between each major tick mark. * If you have a slider with a range from 0 to 50 and the major tick spacing * is set to 10, you will get major ticks next to the following values: * @return the number of values between major ticks * @see #setMajorTickSpacing * This method sets the major tick spacing. The number that is passed in * represents the distance, measured in values, between each major tick mark. * If you have a slider with a range from 0 to 50 and the major tick spacing * is set to 10, you will get major ticks next to the following values: * In order for major ticks to be painted, {@code setPaintTicks} must be * This method will also set up a label table for you. * If there is not already a label table, and the major tick spacing is * {@code > 0}, and {@code getPaintLabels} returns * {@code true}, a standard label table will be generated (by calling * {@code createStandardLabels}) with labels at the major tick marks. * For the example above, you would get text labels: "0", * "10", "20", "30", "40", "50". * The label table is then set on the slider by calling * @param n new value for the {@code majorTickSpacing} property * @see #getMajorTickSpacing * @see #createStandardLabels(int) * attribute: visualUpdate true * description: Sets the number of values between major tick marks. * This method returns the minor tick spacing. The number that is returned * represents the distance, measured in values, between each minor tick mark. * If you have a slider with a range from 0 to 50 and the minor tick spacing * is set to 10, you will get minor ticks next to the following values: * @return the number of values between minor ticks * @see #getMinorTickSpacing * This method sets the minor tick spacing. The number that is passed in * represents the distance, measured in values, between each minor tick mark. * If you have a slider with a range from 0 to 50 and the minor tick spacing * is set to 10, you will get minor ticks next to the following values: * In order for minor ticks to be painted, {@code setPaintTicks} must be * @param n new value for the {@code minorTickSpacing} property * @see #getMinorTickSpacing * attribute: visualUpdate true * description: Sets the number of values between minor tick marks. * Returns true if the knob (and the data value it represents) * resolve to the closest tick mark next to where the user * @return true if the value snaps to the nearest tick mark, else false * Returns true if the knob (and the data value it represents) * resolve to the closest slider value next to where the user * @return true if the value snaps to the nearest slider value, else false * Specifying true makes the knob (and the data value it represents) * resolve to the closest tick mark next to where the user * By default, this property is {@code false}. * @param b true to snap the knob to the nearest tick mark * description: If true snap the knob to the nearest tick mark. * Specifying true makes the knob (and the data value it represents) * resolve to the closest slider value next to where the user * positioned the knob. If the {@code snapToTicks} property has also been * set to {@code true}, the snap-to-ticks behavior will prevail. * By default, the snapToValue property is {@code true}. * @param b true to snap the knob to the nearest slider value * description: If true snap the knob to the nearest slider value. * Tells if tick marks are to be painted. * @return true if tick marks are painted, else false * Determines whether tick marks are painted on the slider. * By default, this property is {@code false}. * @param b whether or not tick marks should be painted * attribute: visualUpdate true * description: If true tick marks are painted on the slider. * Tells if the track (area the slider slides in) is to be painted. * @return true if track is painted, else false * Determines whether the track is painted on the slider. * By default, this property is {@code true}. * @param b whether or not to paint the slider track * attribute: visualUpdate true * description: If true, the track is painted on the slider. * Tells if labels are to be painted. * @return true if labels are painted, else false * Determines whether labels are painted on the slider. * This method will also set up a label table for you. * If there is not already a label table, and the major tick spacing is * a standard label table will be generated (by calling * {@code createStandardLabels}) with labels at the major tick marks. * The label table is then set on the slider by calling * By default, this property is {@code false}. * @param b whether or not to paint labels * @see #createStandardLabels(int) * attribute: visualUpdate true * description: If true labels are painted on the slider. * See readObject() and writeObject() in JComponent for more * information about serialization in Swing. * Returns a string representation of this JSlider. This method * is intended to be used only for debugging purposes, and the * content and format of the returned string may vary between * implementations. The returned string may be empty but may not * @return a string representation of this JSlider. "HORIZONTAL" :
"VERTICAL");
* Gets the AccessibleContext associated with this JSlider. * For sliders, the AccessibleContext takes the form of an * A new AccessibleJSlider instance is created if necessary. * @return an AccessibleJSlider that serves as the * AccessibleContext of this JSlider * This class implements accessibility support for the * <code>JSlider</code> class. It provides an implementation of the * Java Accessibility API appropriate to slider user-interface elements. * <strong>Warning:</strong> * Serialized objects of this class will not be compatible with * future Swing releases. The current serialization support is * appropriate for short term storage or RMI between applications running * the same version of Swing. As of 1.4, support for long term storage * of all JavaBeans<sup><font size="-2">TM</font></sup> * has been added to the <code>java.beans</code> package. * Get the state set of this object. * @return an instance of AccessibleState containing the current state * Get the role of this object. * @return an instance of AccessibleRole describing the role of the object * Get the AccessibleValue associated with this object. In the * implementation of the Java Accessibility API for this class, * return this object, which is responsible for implementing the * AccessibleValue interface on behalf of itself. * Get the accessible value of this object. * @return The current value of this object. * Set the value of this object as a Number. * @return True if the value was set. * Get the minimum accessible value of this object. * @return The minimum value of this object. * Get the maximum accessible value of this object. * @return The maximum value of this object.