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 */ EnumControl(Type type, Object[] values, Object value)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 */ setValue(Object value)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 */ getValue()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 */ getValues()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 */ isValueSupported(Object value)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 */ toString()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 */ Type(String name)209 protected Type(String name) { 210 super(name); 211 } 212 } // class Type 213 214 } // class EnumControl 215