001 /*
002 * Copyright 1999-2003 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.sound.sampled;
027
028 /**
029 * A <code>EnumControl</code> provides control over a set of
030 * discrete possible values, each represented by an object. In a
031 * graphical user interface, such a control might be represented
032 * by a set of buttons, each of which chooses one value or setting. For
033 * example, a reverb control might provide several preset reverberation
034 * settings, instead of providing continuously adjustable parameters
035 * of the sort that would be represented by <code>{@link FloatControl}</code>
036 * objects.
037 * <p>
038 * Controls that provide a choice between only two settings can often be implemented
039 * instead as a <code>{@link BooleanControl}</code>, and controls that provide
040 * a set of values along some quantifiable dimension might be implemented
041 * instead as a <code>FloatControl</code> with a coarse resolution.
042 * However, a key feature of <code>EnumControl</code> is that the returned values
043 * are arbitrary objects, rather than numerical or boolean values. This means that each
044 * returned object can provide further information. As an example, the settings
045 * of a <code>{@link EnumControl.Type#REVERB REVERB}</code> control are instances of
046 * <code>{@link ReverbType}</code> that can be queried for the parameter values
047 * used for each setting.
048 *
049 * @author Kara Kytle
050 * @version 1.21, 07/05/05
051 * @since 1.3
052 */
053 public abstract class EnumControl extends Control {
054
055 // TYPE DEFINES
056
057 // INSTANCE VARIABLES
058
059 /**
060 * The set of possible values.
061 */
062 private Object[] values;
063
064 /**
065 * The current value.
066 */
067 private Object value;
068
069 // CONSTRUCTORS
070
071 /**
072 * Constructs a new enumerated control object with the given parameters.
073 *
074 * @param type the type of control represented this enumerated control object
075 * @param values the set of possible values for the control
076 * @param value the initial control value
077 */
078 protected EnumControl(Type type, Object[] values, Object value) {
079
080 super (type);
081
082 this .values = values;
083 this .value = value;
084 }
085
086 // METHODS
087
088 /**
089 * Sets the current value for the control. The default implementation
090 * simply sets the value as indicated. If the value indicated is not
091 * supported, an IllegalArgumentException is thrown.
092 * Some controls require that their line be open before they can be affected
093 * by setting a value.
094 * @param value the desired new value
095 * @throws IllegalArgumentException if the value indicated does not fall
096 * within the allowable range
097 */
098 public void setValue(Object value) {
099 if (!isValueSupported(value)) {
100 throw new IllegalArgumentException("Requested value "
101 + value + " is not supported.");
102 }
103
104 this .value = value;
105 }
106
107 /**
108 * Obtains this control's current value.
109 * @return the current value
110 */
111 public Object getValue() {
112 return value;
113 }
114
115 /**
116 * Returns the set of possible values for this control.
117 * @return the set of possible values
118 */
119 public Object[] getValues() {
120
121 Object[] localArray = new Object[values.length];
122
123 for (int i = 0; i < values.length; i++) {
124 localArray[i] = values[i];
125 }
126
127 return localArray;
128 }
129
130 /**
131 * Indicates whether the value specified is supported.
132 * @param value the value for which support is queried
133 * @return <code>true</code> if the value is supported,
134 * otherwise <code>false</code>
135 */
136 private boolean isValueSupported(Object value) {
137
138 for (int i = 0; i < values.length; i++) {
139 //$$fb 2001-07-20: Fix for bug 4400392: setValue() in ReverbControl always throws Exception
140 //if (values.equals(values[i])) {
141 if (value.equals(values[i])) {
142 return true;
143 }
144 }
145
146 return false;
147 }
148
149 // ABSTRACT METHOD IMPLEMENTATIONS: CONTROL
150
151 /**
152 * Provides a string representation of the control.
153 * @return a string description
154 */
155 public String toString() {
156 return new String(getType() + " with current value: "
157 + getValue());
158 }
159
160 // INNER CLASSES
161
162 /**
163 * An instance of the <code>EnumControl.Type</code> inner class identifies one kind of
164 * enumerated control. Static instances are provided for the
165 * common types.
166 *
167 * @see EnumControl
168 *
169 * @author Kara Kytle
170 * @version 1.21, 07/05/05
171 * @since 1.3
172 */
173 public static class Type extends Control.Type {
174
175 // TYPE DEFINES
176
177 /**
178 * Represents a control over a set of possible reverberation settings.
179 * Each reverberation setting is described by an instance of the
180 * {@link ReverbType} class. (To access these settings,
181 * invoke <code>{@link EnumControl#getValues}</code> on an
182 * enumerated control of type <code>REVERB</code>.)
183 */
184 public static final Type REVERB = new Type("Reverb");
185
186 // CONSTRUCTOR
187
188 /**
189 * Constructs a new enumerated control type.
190 * @param name the name of the new enumerated control type
191 */
192 protected Type(String name) {
193 super (name);
194 }
195 } // class Type
196
197 } // class EnumControl
|