Interface VariableLight
-
- All Superinterfaces:
AnalogIO
,java.lang.Comparable<NamedBean>
,DigitalIO
,Light
,NamedBean
,PropertyChangeProvider
- All Known Implementing Classes:
AbstractVariableLight
,AnymaDMX_UsbLight
,BiDiBLight
,MqttLight
,SerialLight
,SerialX10Light
,SpecificDmxLight
,SpecificInsteonLight
,SpecificInsteonLight
,SpecificLight
,SpecificLight
,SpecificLight
,SpecificX10Light
,SpecificX10Light
public interface VariableLight extends Light, AnalogIO
Represent a single visible Variable Light on the physical layout.Each Light may have one or more control mechanisms. Control mechanism types are defined here. If a Light has any controls, the information is contained in LightControl objects, which are referenced via that Light.
Lights have a state and an intensity.
The intensity of the hardware output is represented by the range from 0.0 to 1.0, with 1.0 being brightest.
The primary states are:
- ON, corresponding to maximum intensity
- INTERMEDIATE, some value between maximum and minimum
- OFF, corresponding to minimum intensity
The light has a TargetIntensity property which can be set directly. In addition, it has a CurrentIntensity property which may differ from TargetIntensity while the Light is being moved from one intensity to another.
Intensity is limited by MinIntensity and MaxIntensity parameters. Setting the state to ON sets the TargetIntensity to MinIntensity, and to OFF sets the TargetIntensity to MaxIntensity. Attempting to directly set the TargetIntensity outside the values of MinIntensity and MaxIntensity (inclusive) will result in the TargetIntensity being set to the relevant limit.
Because the actual light hardware has only finite resolution, the intensity value is mapped to the nearest setting. For example, in the special case of a two-state (on/off) Light, setting a TargetIntensity of more than 0.5 will turn the Light on, less than 0.5 will turn the light off.
Specific implementations will describe how the settings map to the particular hardware commands.
The transition rate is absolute; the intensity changes at a constant rate regardless of whether the change is a big one or a small one.
This file is part of JMRI.JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.
JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface jmri.AnalogIO
AnalogIO.AbsoluteOrRelative
-
Nested classes/interfaces inherited from interface jmri.NamedBean
NamedBean.BadNameException, NamedBean.BadSystemNameException, NamedBean.BadUserNameException, NamedBean.DisplayOptions, NamedBean.DuplicateSystemNameException
-
-
Field Summary
-
Fields inherited from interface jmri.Light
FAST_CLOCK_CONTROL, INTERMEDIATE, NO_CONTROL, SENSOR_CONTROL, TIMED_ON_CONTROL, TRANSITIONING, TRANSITIONINGHIGHER, TRANSITIONINGLOWER, TRANSITIONINGTOFULLOFF, TRANSITIONINGTOFULLON, TURNOUT_STATUS_CONTROL, TWO_SENSOR_CONTROL
-
Fields inherited from interface jmri.NamedBean
DISPLAY_NAME_FORMAT, INCONSISTENT, PROPERTY_STATE, QUOTED_NAME_FORMAT, UNKNOWN
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description double
getCurrentIntensity()
Get the current intensity value.double
getMaxIntensity()
Get the current value of the maxIntensity property.double
getMinIntensity()
Get the current value of the minIntensity property.double
getTargetIntensity()
Get the target intensity value for the current transition, if any.double
getTransitionTime()
Get the number of fastclock minutes taken by a transition from full ON to full OFF or vice versa.default boolean
isConsistentState()
Show whether state is stable.default boolean
isConsistentValue()
Show whether the analog value is stable.boolean
isTransitionAvailable()
Can the Light change its intensity setting slowly?boolean
isTransitioning()
Convenience method for checking if the intensity of the light is currently changing due to a transition.default void
requestUpdateFromLayout()
Request an update from the layout soft/hardware.void
setMaxIntensity(double intensity)
Set the value of the maxIntensity property.void
setMinIntensity(double intensity)
Set the value of the minIntensity property.void
setTargetIntensity(double intensity)
Set the intended new intensity value for the Light.void
setTransitionTime(double minutes)
Set the fast-clock duration for a transition from full ON to full OFF or vice-versa.-
Methods inherited from interface jmri.AnalogIO
getAbsoluteOrRelative, getCommandedAnalogValue, getKnownAnalogValue, getMax, getMin, getResolution, getState, setCommandedAnalogValue, setState
-
Methods inherited from interface jmri.Light
activateLight, addLightControl, clearLightControls, deactivateLight, getCommandedState, getEnabled, getKnownState, getLightControlList, getState, setCommandedState, setEnabled, setState
-
Methods inherited from interface jmri.NamedBean
addPropertyChangeListener, addPropertyChangeListener, compareSystemNameSuffix, compareTo, describeState, dispose, getBeanType, getComment, getDisplayName, getDisplayName, getListenerRef, getListenerRefs, getNumPropertyChangeListeners, getProperty, getPropertyChangeListenersByReference, getPropertyKeys, getSystemName, getUsageReport, getUserName, removeProperty, setComment, setProperty, setUserName, toString, updateListenerRef, vetoableChange
-
Methods inherited from interface jmri.beans.PropertyChangeProvider
addPropertyChangeListener, addPropertyChangeListener, getPropertyChangeListeners, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener
-
-
-
-
Method Detail
-
requestUpdateFromLayout
@InvokeOnLayoutThread default void requestUpdateFromLayout()
Request an update from the layout soft/hardware. May not even happen, and if it does it will happen later; listen for the result.- Specified by:
requestUpdateFromLayout
in interfaceAnalogIO
- Specified by:
requestUpdateFromLayout
in interfaceDigitalIO
- Specified by:
requestUpdateFromLayout
in interfaceLight
-
isConsistentState
default boolean isConsistentState()
Show whether state is stable. For turnouts, a consistent state is one you can safely run trains over. For lights, it's a state which is either on or off, not in between.- Specified by:
isConsistentState
in interfaceDigitalIO
- Specified by:
isConsistentState
in interfaceLight
- Returns:
- true if state is valid and the known state is the same as commanded
-
isConsistentValue
default boolean isConsistentValue()
Show whether the analog value is stable.- Specified by:
isConsistentValue
in interfaceAnalogIO
- Returns:
- true if the analog value is stable
-
setTargetIntensity
@InvokeOnLayoutThread void setTargetIntensity(double intensity)
Set the intended new intensity value for the Light. If transitions are in use, they will be applied.Bound property between 0 and 1.
A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.
Attempting to set a value below the MinIntensity property value will result in MinIntensity being set. Similarly, setting a value above MaxIntensity will result in MaxINtensity being set.
Setting the intensity to the value of the MinIntensity property will result in the Light going to the OFF state at the end of the transition. Similarly, setting the intensity to the MaxIntensity value will result in the Light going to the ON state at the end of the transition.
All others result in the INTERMEDIATE state.
Light implementations with isIntensityVariable false may not have their TargetIntensity set to values between MinIntensity and MaxIntensity, which would result in the INTERMEDIATE state, as that is invalid for them.
If a non-zero value is set in the transitionTime property, the state will be one of TRANSITIONTOFULLON, TRANSITIONHIGHER, TRANSITIONLOWER or TRANSITIONTOFULLOFF until the transition is complete.
- Parameters:
intensity
- the desired brightness- Throws:
java.lang.IllegalArgumentException
- when intensity is less than 0.0 or more than 1.0java.lang.IllegalArgumentException
- if isIntensityVariable is false and the new value is between MaxIntensity and MinIntensity
-
getCurrentIntensity
double getCurrentIntensity()
Get the current intensity value. If the Light is currently transitioning, this may be either an intermediate or final value.A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.
- Returns:
- the current brightness
-
getTargetIntensity
double getTargetIntensity()
Get the target intensity value for the current transition, if any. If the Light is not currently transitioning, this is the current intensity value.A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.
Bound property
- Returns:
- the desired brightness
-
setMaxIntensity
@InvokeOnLayoutThread void setMaxIntensity(double intensity)
Set the value of the maxIntensity property.Bound property between 0 and 1.
A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.
- Parameters:
intensity
- the maximum brightness- Throws:
java.lang.IllegalArgumentException
- when intensity is less than 0.0 or more than 1.0java.lang.IllegalArgumentException
- when intensity is not greater than the current value of the minIntensity property
-
getMaxIntensity
double getMaxIntensity()
Get the current value of the maxIntensity property.A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.
- Returns:
- the maximum brightness
-
setMinIntensity
@InvokeOnLayoutThread void setMinIntensity(double intensity)
Set the value of the minIntensity property.Bound property between 0 and 1.
A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.
- Parameters:
intensity
- the minimum brightness- Throws:
java.lang.IllegalArgumentException
- when intensity is less than 0.0 or more than 1.0java.lang.IllegalArgumentException
- when intensity is not less than the current value of the maxIntensity property
-
getMinIntensity
double getMinIntensity()
Get the current value of the minIntensity property.A value of 0.0 corresponds to full off, and a value of 1.0 corresponds to full on.
- Returns:
- the minimum brightness
-
isTransitionAvailable
boolean isTransitionAvailable()
Can the Light change its intensity setting slowly?If true, this Light supports a non-zero value of the transitionTime property, which controls how long the Light will take to change from one intensity level to another.
Unbound property
- Returns:
- true if brightness can fade between two states; false otherwise
-
setTransitionTime
@InvokeOnLayoutThread void setTransitionTime(double minutes)
Set the fast-clock duration for a transition from full ON to full OFF or vice-versa.Note there is no guarantee of how this scales when other changes in intensity take place. In particular, some Light implementations will change at a constant fraction per fastclock minute and some will take a fixed duration regardless of the size of the intensity change.
Bound property
- Parameters:
minutes
- time to fade- Throws:
java.lang.IllegalArgumentException
- if isTransitionAvailable() is false and minutes is not 0.0java.lang.IllegalArgumentException
- if minutes is negative
-
getTransitionTime
double getTransitionTime()
Get the number of fastclock minutes taken by a transition from full ON to full OFF or vice versa.- Returns:
- 0.0 if the output intensity transition is instantaneous
-
isTransitioning
boolean isTransitioning()
Convenience method for checking if the intensity of the light is currently changing due to a transition.Bound property so that listeners can conveniently learn when the transition is over.
- Returns:
- true if light is between two states; false otherwise
-
-