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 */ EnumControl(Type type, Object[] values, Object value)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 */ setValue(Object value)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 */ getValue()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 */ getValues()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 */ isValueSupported(Object value)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 toString()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 */ Type(final String name)168 protected Type(final String name) { 169 super(name); 170 } 171 } 172 } 173