1 /*
2 * Copyright (c) 1999, 2020, 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 * An {@code EnumControl} provides control over a set of discrete possible
30 * values, each represented by an object. In a graphical user interface, such a
31 * control might be represented by a set of buttons, each of which chooses one
32 * value or setting. For example, a reverb control might provide several preset
33 * reverberation settings, instead of providing continuously adjustable
34 * parameters of the sort that would be represented by {@link FloatControl}
35 * objects.
36 * <p>
37 * Controls that provide a choice between only two settings can often be
38 * implemented instead as a {@link BooleanControl}, and controls that provide a
39 * set of values along some quantifiable dimension might be implemented instead
40 * as a {@code FloatControl} with a coarse resolution. However, a key feature of
41 * {@code EnumControl} is that the returned values are arbitrary objects, rather
42 * than numerical or boolean values. This means that each returned object can
43 * provide further information. As an example, the settings of a
44 * {@link EnumControl.Type#REVERB REVERB} control are instances of
45 * {@link ReverbType} that can be queried for the parameter values used for each
46 * setting.
47 *
48 * @author Kara Kytle
49 * @since 1.3
50 */
51 public abstract class EnumControl extends Control {
52
53 /**
54 * The set of possible values.
55 */
56 private final Object[] values;
57
58 /**
59 * The current value.
60 */
61 private Object value;
62
63 /**
64 * Constructs a new enumerated control object with the given parameters.
65 *
66 * @param type the type of control represented this enumerated control
67 * object
68 * @param values the set of possible values for the control
69 * @param value the initial control value
70 */
71 protected EnumControl(Type type, Object[] values, Object value) {
72 super(type);
73 this.values = values;
74 this.value = value;
75 }
76
77 /**
78 * Sets the current value for the control. The default implementation simply
79 * sets the value as indicated. If the value indicated is not supported, an
80 * {@code IllegalArgumentException} is thrown. Some controls require that
81 * their line be open before they can be affected by setting a value.
82 *
83 * @param value the desired new value
84 * @throws IllegalArgumentException if the value indicated does not fall
85 * within the allowable range
86 */
87 public void setValue(Object value) {
88 if (!isValueSupported(value)) {
89 throw new IllegalArgumentException("Requested value " + value + " is not supported.");
90 }
91
92 this.value = value;
93 }
94
95 /**
96 * Obtains this control's current value.
97 *
98 * @return the current value
99 */
100 public Object getValue() {
101 return value;
102 }
103
104 /**
105 * Returns the set of possible values for this control.
106 *
107 * @return the set of possible values
108 */
109 public Object[] getValues() {
110 return values.clone();
111 }
112
113 /**
114 * Indicates whether the value specified is supported.
115 *
116 * @param value the value for which support is queried
117 * @return {@code true} if the value is supported, otherwise {@code false}
118 */
119 private boolean isValueSupported(Object value) {
120
121 for (int i = 0; i < values.length; i++) {
122 //$$fb 2001-07-20: Fix for bug 4400392: setValue() in ReverbControl always throws Exception
123 //if (values.equals(values[i])) {
124 if (value.equals(values[i])) {
125 return true;
126 }
127 }
128
129 return false;
130 }
131
132 /**
133 * Returns a string representation of the enumerated control.
134 *
135 * @return a string representation of the enumerated control
136 */
137 @Override
138 public String toString() {
139 return String.format("%s with current value: %s", super.toString(),
140 getValue());
141 }
142
143 /**
144 * An instance of the {@code EnumControl.Type} inner class identifies one
145 * kind of enumerated control. Static instances are provided for the common
146 * types.
147 *
148 * @author Kara Kytle
149 * @see EnumControl
150 * @since 1.3
151 */
152 public static class Type extends Control.Type {
153
154 /**
155 * Represents a control over a set of possible reverberation settings.
156 * Each reverberation setting is described by an instance of the
157 * {@link ReverbType} class. (To access these settings, invoke
158 * {@link EnumControl#getValues} on an enumerated control of type
159 * {@code REVERB}.)
160 */
161 public static final Type REVERB = new Type("Reverb");
162
163 /**
164 * Constructs a new enumerated control type.
165 *
166 * @param name the name of the new enumerated control type
167 */
168 protected Type(final String name) {
169 super(name);
170 }
171 }
172 }