Java example source code file (FloatControl.java)
The FloatControl.java Java example source code/*
* Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.sound.sampled;
/**
* A <code>FloatControl object provides control over a range of
* floating-point values. Float controls are often
* represented in graphical user interfaces by continuously
* adjustable objects such as sliders or rotary knobs. Concrete subclasses
* of <code>FloatControl implement controls, such as gain and pan, that
* affect a line's audio signal in some way that an application can manipulate.
* The <code>{@link FloatControl.Type}
* inner class provides static instances of types that are used to
* identify some common kinds of float control.
* <p>
* The <code>FloatControl abstract class provides methods to set and get
* the control's current floating-point value. Other methods obtain the possible
* range of values and the control's resolution (the smallest increment between
* returned values). Some float controls allow ramping to a
* new value over a specified period of time. <code>FloatControl also
* includes methods that return string labels for the minimum, maximum, and midpoint
* positions of the control.
*
* @see Line#getControls
* @see Line#isControlSupported
*
* @author David Rivas
* @author Kara Kytle
* @since 1.3
*/
public abstract class FloatControl extends Control {
// INSTANCE VARIABLES
// FINAL VARIABLES
/**
* The minimum supported value.
*/
private float minimum;
/**
* The maximum supported value.
*/
private float maximum;
/**
* The control's precision.
*/
private float precision;
/**
* The smallest time increment in which a value change
* can be effected during a value shift, in microseconds.
*/
private int updatePeriod;
/**
* A label for the units in which the control values are expressed,
* such as "dB" for decibels.
*/
private final String units;
/**
* A label for the minimum value, such as "Left."
*/
private final String minLabel;
/**
* A label for the maximum value, such as "Right."
*/
private final String maxLabel;
/**
* A label for the mid-point value, such as "Center."
*/
private final String midLabel;
// STATE VARIABLES
/**
* The current value.
*/
private float value;
// CONSTRUCTORS
/**
* Constructs a new float control object with the given parameters
*
* @param type the kind of control represented by this float control object
* @param minimum the smallest value permitted for the control
* @param maximum the largest value permitted for the control
* @param precision the resolution or granularity of the control.
* This is the size of the increment between discrete valid values.
* @param updatePeriod the smallest time interval, in microseconds, over which the control
* can change from one discrete value to the next during a {@link #shift(float,float,int) shift}
* @param initialValue the value that the control starts with when constructed
* @param units the label for the units in which the control's values are expressed,
* such as "dB" or "frames per second"
* @param minLabel the label for the minimum value, such as "Left" or "Off"
* @param midLabel the label for the midpoint value, such as "Center" or "Default"
* @param maxLabel the label for the maximum value, such as "Right" or "Full"
*
* @throws IllegalArgumentException if {@code minimum} is greater
* than {@code maximum} or {@code initialValue} does not fall
* within the allowable range
*/
protected FloatControl(Type type, float minimum, float maximum,
float precision, int updatePeriod, float initialValue,
String units, String minLabel, String midLabel, String maxLabel) {
super(type);
if (minimum > maximum) {
throw new IllegalArgumentException("Minimum value " + minimum
+ " exceeds maximum value " + maximum + ".");
}
if (initialValue < minimum) {
throw new IllegalArgumentException("Initial value " + initialValue
+ " smaller than allowable minimum value " + minimum + ".");
}
if (initialValue > maximum) {
throw new IllegalArgumentException("Initial value " + initialValue
+ " exceeds allowable maximum value " + maximum + ".");
}
this.minimum = minimum;
this.maximum = maximum;
this.precision = precision;
this.updatePeriod = updatePeriod;
this.value = initialValue;
this.units = units;
this.minLabel = ( (minLabel == null) ? "" : minLabel);
this.midLabel = ( (midLabel == null) ? "" : midLabel);
this.maxLabel = ( (maxLabel == null) ? "" : maxLabel);
}
/**
* Constructs a new float control object with the given parameters.
* The labels for the minimum, maximum, and mid-point values are set
* to zero-length strings.
*
* @param type the kind of control represented by this float control object
* @param minimum the smallest value permitted for the control
* @param maximum the largest value permitted for the control
* @param precision the resolution or granularity of the control.
* This is the size of the increment between discrete valid values.
* @param updatePeriod the smallest time interval, in microseconds, over which the control
* can change from one discrete value to the next during a {@link #shift(float,float,int) shift}
* @param initialValue the value that the control starts with when constructed
* @param units the label for the units in which the control's values are expressed,
* such as "dB" or "frames per second"
*
* @throws IllegalArgumentException if {@code minimum} is greater
* than {@code maximum} or {@code initialValue} does not fall
* within the allowable range
*/
protected FloatControl(Type type, float minimum, float maximum,
float precision, int updatePeriod, float initialValue, String units) {
this(type, minimum, maximum, precision, updatePeriod,
initialValue, units, "", "", "");
}
// METHODS
/**
* Sets the current value for the control. The default implementation
* simply sets the value as indicated. If the value indicated is greater
* than the maximum value, or smaller than the minimum value, an
* IllegalArgumentException is thrown.
* Some controls require that their line be open before they can be affected
* by setting a value.
* @param newValue desired new value
* @throws IllegalArgumentException if the value indicated does not fall
* within the allowable range
*/
public void setValue(float newValue) {
if (newValue > maximum) {
throw new IllegalArgumentException("Requested value " + newValue + " exceeds allowable maximum value " + maximum + ".");
}
if (newValue < minimum) {
throw new IllegalArgumentException("Requested value " + newValue + " smaller than allowable minimum value " + minimum + ".");
}
value = newValue;
}
/**
* Obtains this control's current value.
* @return the current value
*/
public float getValue() {
return value;
}
/**
* Obtains the maximum value permitted.
* @return the maximum allowable value
*/
public float getMaximum() {
return maximum;
}
/**
* Obtains the minimum value permitted.
* @return the minimum allowable value
*/
public float getMinimum() {
return minimum;
}
/**
* Obtains the label for the units in which the control's values are expressed,
* such as "dB" or "frames per second."
* @return the units label, or a zero-length string if no label
*/
public String getUnits() {
return units;
}
/**
* Obtains the label for the minimum value, such as "Left" or "Off."
* @return the minimum value label, or a zero-length string if no label * has been set
*/
public String getMinLabel() {
return minLabel;
}
/**
* Obtains the label for the mid-point value, such as "Center" or "Default."
* @return the mid-point value label, or a zero-length string if no label * has been set
*/
public String getMidLabel() {
return midLabel;
}
/**
* Obtains the label for the maximum value, such as "Right" or "Full."
* @return the maximum value label, or a zero-length string if no label * has been set
*/
public String getMaxLabel() {
return maxLabel;
}
/**
* Obtains the resolution or granularity of the control, in the units
* that the control measures.
* The precision is the size of the increment between discrete valid values
* for this control, over the set of supported floating-point values.
* @return the control's precision
*/
public float getPrecision() {
return precision;
}
/**
* Obtains the smallest time interval, in microseconds, over which the control's value can
* change during a shift. The update period is the inverse of the frequency with which
* the control updates its value during a shift. If the implementation does not support value shifting over
* time, it should set the control's value to the final value immediately
* and return -1 from this method.
*
* @return update period in microseconds, or -1 if shifting over time is unsupported
* @see #shift
*/
public int getUpdatePeriod() {
return updatePeriod;
}
/**
* Changes the control value from the initial value to the final
* value linearly over the specified time period, specified in microseconds.
* This method returns without blocking; it does not wait for the shift
* to complete. An implementation should complete the operation within the time
* specified. The default implementation simply changes the value
* to the final value immediately.
*
* @param from initial value at the beginning of the shift
* @param to final value after the shift
* @param microseconds maximum duration of the shift in microseconds
*
* @throws IllegalArgumentException if either {@code from} or {@code to}
* value does not fall within the allowable range
*
* @see #getUpdatePeriod
*/
public void shift(float from, float to, int microseconds) {
// test "from" value, "to" value will be tested by setValue()
if (from < minimum) {
throw new IllegalArgumentException("Requested value " + from
+ " smaller than allowable minimum value " + minimum + ".");
}
if (from > maximum) {
throw new IllegalArgumentException("Requested value " + from
+ " exceeds allowable maximum value " + maximum + ".");
}
setValue(to);
}
// ABSTRACT METHOD IMPLEMENTATIONS: CONTROL
/**
* Provides a string representation of the control
* @return a string description
*/
public String toString() {
return new String(getType() + " with current value: " + getValue() + " " + units +
" (range: " + minimum + " - " + maximum + ")");
}
// INNER CLASSES
/**
* An instance of the <code>FloatControl.Type inner class identifies one kind of
* float control. Static instances are provided for the
* common types.
*
* @author Kara Kytle
* @since 1.3
*/
public static class Type extends Control.Type {
// TYPE DEFINES
// GAIN TYPES
/**
* Represents a control for the overall gain on a line.
* <p>
* Gain is a quantity in decibels (dB) that is added to the intrinsic
* decibel level of the audio signal--that is, the level of
* the signal before it is altered by the gain control. A positive
* gain amplifies (boosts) the signal's volume, and a negative gain
* attenuates (cuts) it.
* The gain setting defaults to a value of 0.0 dB, meaning the signal's
* loudness is unaffected. Note that gain measures dB, not amplitude.
* The relationship between a gain in decibels and the corresponding
* linear amplitude multiplier is:
*
*<CENTER>
Other Java examples (source code examples)Here is a short list of links related to this Java FloatControl.java source code file: |
The search page
Other Java source code examples at this package level
Click here to learn more about this project
