1 /*
2 * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.sound.sampled;
27
28 /**
29 * A <code>EnumControl</code> provides control over a set of
30 * discrete possible values, each represented by an object. In a
31 * graphical user interface, such a control might be represented
32 * by a set of buttons, each of which chooses one value or setting. For
33 * example, a reverb control might provide several preset reverberation
34 * settings, instead of providing continuously adjustable parameters
35 * of the sort that would be represented by <code>{@link FloatControl}</code>
36 * objects.
37 * <p>
38 * Controls that provide a choice between only two settings can often be implemented
39 * instead as a <code>{@link BooleanControl}</code>, and controls that provide
40 * a set of values along some quantifiable dimension might be implemented
41 * instead as a <code>FloatControl</code> with a coarse resolution.
42 * However, a key feature of <code>EnumControl</code> is that the returned values
43 * are arbitrary objects, rather than numerical or boolean values. This means that each
44 * returned object can provide further information. As an example, the settings
45 * of a <code>{@link EnumControl.Type#REVERB REVERB}</code> control are instances of
46 * <code>{@link ReverbType}</code> that can be queried for the parameter values
47 * used for each setting.
48 *
49 * @author Kara Kytle
50 * @since 1.3
51 */
52 public abstract class EnumControl extends Control {
53
54
55 // TYPE DEFINES
56
57
58 // INSTANCE VARIABLES
59
60
61 /**
62 * The set of possible values.
63 */
64 private Object[] values;
65
66
67 /**
68 * The current value.
69 */
70 private Object value;
71
72
73
74 // CONSTRUCTORS
75
76
77 /**
78 * Constructs a new enumerated control object with the given parameters.
79 *
80 * @param type the type of control represented this enumerated control object
81 * @param values the set of possible values for the control
82 * @param value the initial control value
83 */
84 protected EnumControl(Type type, Object[] values, Object value) {
85
86 super(type);
87
88 this.values = values;
89 this.value = value;
90 }
91
92
93
94 // METHODS
95
96
97 /**
98 * Sets the current value for the control. The default implementation
99 * simply sets the value as indicated. If the value indicated is not
100 * supported, an IllegalArgumentException is thrown.
101 * Some controls require that their line be open before they can be affected
102 * by setting a value.
103 * @param value the desired new value
104 * @throws IllegalArgumentException if the value indicated does not fall
105 * within the allowable range
106 */
107 public void setValue(Object value) {
108 if (!isValueSupported(value)) {
109 throw new IllegalArgumentException("Requested value " + value + " is not supported.");
110 }
111
112 this.value = value;
113 }
114
115
116 /**
117 * Obtains this control's current value.
118 * @return the current value
119 */
120 public Object getValue() {
121 return value;
122 }
123
124
125 /**
126 * Returns the set of possible values for this control.
127 * @return the set of possible values
128 */
129 public Object[] getValues() {
130
131 Object[] localArray = new Object[values.length];
132
133 for (int i = 0; i < values.length; i++) {
134 localArray[i] = values[i];
135 }
136
137 return localArray;
138 }
139
140
141 /**
142 * Indicates whether the value specified is supported.
143 * @param value the value for which support is queried
144 * @return <code>true</code> if the value is supported,
145 * otherwise <code>false</code>
146 */
147 private boolean isValueSupported(Object value) {
148
149 for (int i = 0; i < values.length; i++) {
150 //$$fb 2001-07-20: Fix for bug 4400392: setValue() in ReverbControl always throws Exception
151 //if (values.equals(values[i])) {
152 if (value.equals(values[i])) {
153 return true;
154 }
155 }
156
157 return false;
158 }
159
160
161
162 // ABSTRACT METHOD IMPLEMENTATIONS: CONTROL
163
164
165 /**
166 * Provides a string representation of the control.
167 * @return a string description
168 */
169 public String toString() {
170 return new String(getType() + " with current value: " + getValue());
171 }
172
173
174 // INNER CLASSES
175
176
177 /**
178 * An instance of the <code>EnumControl.Type</code> inner class identifies one kind of
179 * enumerated control. Static instances are provided for the
180 * common types.
181 *
182 * @see EnumControl
183 *
184 * @author Kara Kytle
185 * @since 1.3
186 */
187 public static class Type extends Control.Type {
188
189
190 // TYPE DEFINES
191
192 /**
193 * Represents a control over a set of possible reverberation settings.
194 * Each reverberation setting is described by an instance of the
195 * {@link ReverbType} class. (To access these settings,
196 * invoke <code>{@link EnumControl#getValues}</code> on an
197 * enumerated control of type <code>REVERB</code>.)
198 */
199 public static final Type REVERB = new Type("Reverb");
200
201
202 // CONSTRUCTOR
203
204
205 /**
206 * Constructs a new enumerated control type.
207 * @param name the name of the new enumerated control type
208 */
209 protected Type(String name) {
210 super(name);
211 }
212 } // class Type
213
214 } // class EnumControl