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  * A {@code BooleanControl} provides the ability to switch between two possible
  30  * settings that affect a line's audio. The settings are boolean values
  31  * ({@code true} and {@code false}). A graphical user interface might represent
  32  * the control by a two-state button, an on/off switch, two mutually exclusive
  33  * buttons, or a checkbox (among other possibilities). For example, depressing a
  34  * button might activate a {@link BooleanControl.Type#MUTE MUTE} control to
  35  * silence the line's audio.
  36  * <p>
  37  * As with other {@code Control} subclasses, a method is provided that returns
  38  * string labels for the values, suitable for display in the user interface.
  39  *
  40  * @author Kara Kytle
  41  * @since 1.3
  42  */
  43 public abstract class BooleanControl extends Control {
  44 
  45     /**
  46      * The {@code true} state label, such as "true" or "on".
  47      */
  48     private final String trueStateLabel;
  49 
  50     /**
  51      * The {@code false} state label, such as "false" or "off".
  52      */
  53     private final String falseStateLabel;
  54 
  55     /**
  56      * The current value.
  57      */
  58     private boolean value;
  59 
  60     /**
  61      * Constructs a new boolean control object with the given parameters.
  62      *
  63      * @param  type the type of control represented this float control object
  64      * @param  initialValue the initial control value
  65      * @param  trueStateLabel the label for the state represented by
  66      *         {@code true}, such as "true" or "on"
  67      * @param  falseStateLabel the label for the state represented by
  68      *         {@code false}, such as "false" or "off"
  69      */
  70     protected BooleanControl(Type type, boolean initialValue, String trueStateLabel, String falseStateLabel) {
  71 
  72         super(type);
  73         this.value = initialValue;
  74         this.trueStateLabel = trueStateLabel;
  75         this.falseStateLabel = falseStateLabel;
  76     }
  77 
  78     /**
  79      * Constructs a new boolean control object with the given parameters. The
  80      * labels for the {@code true} and {@code false} states default to "true"
  81      * and "false".
  82      *
  83      * @param  type the type of control represented by this float control object
  84      * @param  initialValue the initial control value
  85      */
  86     protected BooleanControl(Type type, boolean initialValue) {
  87         this(type, initialValue, "true", "false");
  88     }
  89 
  90     /**
  91      * Sets the current value for the control. The default implementation simply
  92      * sets the value as indicated. Some controls require that their line be
  93      * open before they can be affected by setting a value.
  94      *
  95      * @param  value desired new value
  96      */
  97     public void setValue(boolean value) {
  98         this.value = value;
  99     }
 100 
 101     /**
 102      * Obtains this control's current value.
 103      *
 104      * @return current value
 105      */
 106     public boolean getValue() {
 107         return value;
 108     }
 109 
 110     /**
 111      * Obtains the label for the specified state.
 112      *
 113      * @param  state the state whose label will be returned
 114      * @return the label for the specified state, such as "true" or "on" for
 115      *         {@code true}, or "false" or "off" for {@code false}
 116      */
 117     public String getStateLabel(boolean state) {
 118         return ((state == true) ? trueStateLabel : falseStateLabel);
 119     }
 120 
 121     /**
 122      * Provides a string representation of the control.
 123      *
 124      * @return a string description
 125      */
 126     @Override
 127     public String toString() {
 128         return new String(super.toString() + " with current value: " + getStateLabel(getValue()));
 129     }
 130 
 131     /**
 132      * An instance of the {@code BooleanControl.Type} class identifies one kind
 133      * of boolean control. Static instances are provided for the common types.
 134      *
 135      * @author Kara Kytle
 136      * @since 1.3
 137      */
 138     public static class Type extends Control.Type {
 139 
 140         /**
 141          * Represents a control for the mute status of a line. Note that mute
 142          * status does not affect gain.
 143          */
 144         public static final Type MUTE = new Type("Mute");
 145 
 146         /**
 147          * Represents a control for whether reverberation is applied to a line.
 148          * Note that the status of this control not affect the reverberation
 149          * settings for a line, but does affect whether these settings are used.
 150          */
 151         public static final Type APPLY_REVERB = new Type("Apply Reverb");
 152 
 153         /**
 154          * Constructs a new boolean control type.
 155          *
 156          * @param name the name of the new boolean control type
 157          */
 158         protected Type(final String name) {
 159             super(name);
 160         }
 161     }
 162 }