001package jmri; 002 003/** 004 * Represent a single visible Variable Light on the physical layout. 005 * <p> 006 * Each Light may have one or more control mechanisms. Control mechanism types 007 * are defined here. If a Light has any controls, the information is contained 008 * in LightControl objects, which are referenced via that Light. 009 * <p> 010 * Lights have a state and an intensity. 011 * <p> 012 * The intensity of the hardware output is represented by the range from 0.0 to 013 * 1.0, with 1.0 being brightest. 014 * <p> 015 * The primary states are: 016 * <ul> 017 * <li>ON, corresponding to maximum intensity 018 * <li>INTERMEDIATE, some value between maximum and minimum 019 * <li>OFF, corresponding to minimum intensity 020 * </ul> 021 * The underlying hardware may provide just the ON/OFF two levels, or have a 022 * semi-continuous intensity setting with some number of steps. 023 * <p> 024 * The light has a TargetIntensity property which can be set directly. In 025 * addition, it has a CurrentIntensity property which may differ from 026 * TargetIntensity while the Light is being moved from one intensity to another. 027 * <p> 028 * Intensity is limited by MinIntensity and MaxIntensity parameters. Setting the 029 * state to ON sets the TargetIntensity to MinIntensity, and to OFF sets the 030 * TargetIntensity to MaxIntensity. Attempting to directly set the 031 * TargetIntensity outside the values of MinIntensity and MaxIntensity 032 * (inclusive) will result in the TargetIntensity being set to the relevant 033 * limit. 034 * <p> 035 * Because the actual light hardware has only finite resolution, the intensity 036 * value is mapped to the nearest setting. For example, in the special case of a 037 * two-state (on/off) Light, setting a TargetIntensity of more than 0.5 will 038 * turn the Light on, less than 0.5 will turn the light off. 039 * <p> 040 * Specific implementations will describe how the settings map to the particular 041 * hardware commands. 042 * <p> 043 * The transition rate is absolute; the intensity changes at a constant rate 044 * regardless of whether the change is a big one or a small one. 045 * 046 * <hr> 047 * This file is part of JMRI. 048 * <p> 049 * JMRI is free software; you can redistribute it and/or modify it under the 050 * terms of version 2 of the GNU General Public License as published by the Free 051 * Software Foundation. See the "COPYING" file for a copy of this license. 052 * <p> 053 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY 054 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 055 * A PARTICULAR PURPOSE. See the GNU General Public License for more details. 056 * 057 * @author Dave Duchamp Copyright (C) 2004, 2010 058 * @author Ken Cameron Copyright (C) 2008 059 * @author Bob Jacobsen Copyright (C) 2008 060 */ 061public interface VariableLight extends Light, AnalogIO { 062 063 /** 064 * String constant for the property current intensity. 065 */ 066 String PROPERTY_CURRENT_INTENSITY = "CurrentIntensity"; 067 068 /** 069 * String constant for the property min intensity. 070 */ 071 String PROPERTY_MIN_INTENSITY = "MinIntensity"; 072 073 /** 074 * String constant for the property max intensity. 075 */ 076 String PROPERTY_MAX_INTENSITY = "MaxIntensity"; 077 078 /** {@inheritDoc} */ 079 @Override 080 @InvokeOnLayoutThread 081 default void requestUpdateFromLayout() { 082 // Do nothing 083 } 084 085 /** {@inheritDoc} */ 086 @Override 087 default boolean isConsistentState() { 088 return (getState() == DigitalIO.ON) 089 || (getState() == DigitalIO.OFF) 090 || (getState() == INTERMEDIATE); 091 } 092 093 /** {@inheritDoc} */ 094 @Override 095 default boolean isConsistentValue() { 096 // Assume that the value is consistent if the state is consistent. 097 return isConsistentState(); 098 } 099 100 /** 101 * Set the intended new intensity value for the Light. If transitions are in 102 * use, they will be applied. 103 * <p> 104 * Bound property between 0 and 1. 105 * <p> 106 * A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to 107 * full on. 108 * <p> 109 * Attempting to set a value below the MinIntensity property value will 110 * result in MinIntensity being set. Similarly, setting a value above 111 * MaxIntensity will result in MaxINtensity being set. 112 * <p> 113 * Setting the intensity to the value of the MinIntensity property will 114 * result in the Light going to the OFF state at the end of the transition. 115 * Similarly, setting the intensity to the MaxIntensity value will result in 116 * the Light going to the ON state at the end of the transition. 117 * <p> 118 * All others result in the INTERMEDIATE state. 119 * <p> 120 * Light implementations with isIntensityVariable false may not have their 121 * TargetIntensity set to values between MinIntensity and MaxIntensity, 122 * which would result in the INTERMEDIATE state, as that is invalid for 123 * them. 124 * <p> 125 * If a non-zero value is set in the transitionTime property, the state will 126 * be one of TRANSITIONTOFULLON, TRANSITIONHIGHER, TRANSITIONLOWER or 127 * TRANSITIONTOFULLOFF until the transition is complete. 128 * 129 * @param intensity the desired brightness 130 * @throws IllegalArgumentException when intensity is less than 0.0 or more 131 * than 1.0 132 * @throws IllegalArgumentException if isIntensityVariable is false and the 133 * new value is between MaxIntensity and 134 * MinIntensity 135 */ 136 @InvokeOnLayoutThread 137 void setTargetIntensity(double intensity); 138 139 /** 140 * Get the current intensity value. If the Light is currently transitioning, 141 * this may be either an intermediate or final value. 142 * <p> 143 * A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to 144 * full on. 145 * 146 * @return the current brightness 147 */ 148 double getCurrentIntensity(); 149 150 /** 151 * Get the target intensity value for the current transition, if any. If the 152 * Light is not currently transitioning, this is the current intensity 153 * value. 154 * <p> 155 * A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to 156 * full on. 157 * <p> 158 * Bound property 159 * 160 * @return the desired brightness 161 */ 162 double getTargetIntensity(); 163 164 /** 165 * Set the value of the maxIntensity property. 166 * <p> 167 * Bound property between 0 and 1. 168 * <p> 169 * A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to 170 * full on. 171 * 172 * @param intensity the maximum brightness 173 * @throws IllegalArgumentException when intensity is less than 0.0 or more 174 * than 1.0 175 * @throws IllegalArgumentException when intensity is not greater than the 176 * current value of the minIntensity 177 * property 178 */ 179 @InvokeOnLayoutThread 180 void setMaxIntensity(double intensity); 181 182 /** 183 * Get the current value of the maxIntensity property. 184 * <p> 185 * A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to 186 * full on. 187 * 188 * @return the maximum brightness 189 */ 190 double getMaxIntensity(); 191 192 /** 193 * Set the value of the minIntensity property. 194 * <p> 195 * Bound property between 0 and 1. 196 * <p> 197 * A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to 198 * full on. 199 * 200 * @param intensity the minimum brightness 201 * @throws IllegalArgumentException when intensity is less than 0.0 or more 202 * than 1.0 203 * @throws IllegalArgumentException when intensity is not less than the 204 * current value of the maxIntensity 205 * property 206 */ 207 @InvokeOnLayoutThread 208 void setMinIntensity(double intensity); 209 210 /** 211 * Get the current value of the minIntensity property. 212 * <p> 213 * A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to 214 * full on. 215 * 216 * @return the minimum brightness 217 */ 218 double getMinIntensity(); 219 220 /** 221 * Can the Light change its intensity setting slowly? 222 * <p> 223 * If true, this Light supports a non-zero value of the transitionTime 224 * property, which controls how long the Light will take to change from one 225 * intensity level to another. 226 * <p> 227 * Unbound property 228 * 229 * @return true if brightness can fade between two states; false otherwise 230 */ 231 boolean isTransitionAvailable(); 232 233 /** 234 * Set the fast-clock duration for a transition from full ON to full OFF or 235 * vice-versa. 236 * <p> 237 * Note there is no guarantee of how this scales when other changes in 238 * intensity take place. In particular, some Light implementations will 239 * change at a constant fraction per fastclock minute and some will take a 240 * fixed duration regardless of the size of the intensity change. 241 * <p> 242 * Bound property 243 * @param minutes time to fade 244 * @throws IllegalArgumentException if isTransitionAvailable() is false and 245 * minutes is not 0.0 246 * @throws IllegalArgumentException if minutes is negative 247 */ 248 @InvokeOnLayoutThread 249 void setTransitionTime(double minutes); 250 251 /** 252 * Get the number of fastclock minutes taken by a transition from full ON to 253 * full OFF or vice versa. 254 * 255 * @return 0.0 if the output intensity transition is instantaneous 256 */ 257 double getTransitionTime(); 258 259 /** 260 * Convenience method for checking if the intensity of the light is 261 * currently changing due to a transition. 262 * <p> 263 * Bound property so that listeners can conveniently learn when the 264 * transition is over. 265 * 266 * @return true if light is between two states; false otherwise 267 */ 268 boolean isTransitioning(); 269 270}