Package jmri

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 underlying hardware may provide just the ON/OFF two levels, or have a semi-continuous intensity setting with some number of steps.

    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.

    • Method Detail

      • 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 interface DigitalIO
        Specified by:
        isConsistentState in interface Light
        Returns:
        true if state is valid and the known state is the same as commanded

      • 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.0
        java.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.0
        java.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.0
        java.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.0
        java.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