1 /* 2 * Copyright (c) 1999, 2014, 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 111 Object[] localArray = new Object[values.length]; 112 113 for (int i = 0; i < values.length; i++) { 114 localArray[i] = values[i]; 115 } 116 117 return localArray; 118 } 119 120 /** 121 * Indicates whether the value specified is supported. 122 * 123 * @param value the value for which support is queried 124 * @return {@code true} if the value is supported, otherwise {@code false} 125 */ 126 private boolean isValueSupported(Object value) { 127 128 for (int i = 0; i < values.length; i++) { 129 //$$fb 2001-07-20: Fix for bug 4400392: setValue() in ReverbControl always throws Exception 130 //if (values.equals(values[i])) { 131 if (value.equals(values[i])) { 132 return true; 133 } 134 } 135 136 return false; 137 } 138 139 /** 140 * Provides a string representation of the control. 141 * 142 * @return a string description 143 */ 144 @Override 145 public String toString() { 146 return new String(getType() + " with current value: " + getValue()); 147 } 148 149 /** 150 * An instance of the {@code EnumControl.Type} inner class identifies one 151 * kind of enumerated control. Static instances are provided for the common 152 * types. 153 * 154 * @author Kara Kytle 155 * @see EnumControl 156 * @since 1.3 157 */ 158 public static class Type extends Control.Type { 159 160 /** 161 * Represents a control over a set of possible reverberation settings. 162 * Each reverberation setting is described by an instance of the 163 * {@link ReverbType} class. (To access these settings, invoke 164 * {@link EnumControl#getValues} on an enumerated control of type 165 * {@code REVERB}.) 166 */ 167 public static final Type REVERB = new Type("Reverb"); 168 169 /** 170 * Constructs a new enumerated control type. 171 * 172 * @param name the name of the new enumerated control type 173 */ 174 protected Type(final String name) { 175 super(name); 176 } 177 } 178 }