Package jmri.jmrit.symbolicprog

Class VariableValue

  • All Implemented Interfaces:
    java.beans.PropertyChangeListener, java.util.EventListener
    Direct Known Subclasses:
    ConstantValue, DecVariableValue, EnumVariableValue, LongAddrVariableValue, SpeedTableVarValue, SplitEnumVariableValue, SplitVariableValue
    public abstract class VariableValue
extends AbstractValue
implements java.beans.PropertyChangeListener
    Represents a single Variable value; abstract base class.

    The "changed" parameter (non-bound, accessed via isChanged) indicates whether a "write changes" or "read changes" operation should handle this object.

    The mask shown below comes in two forms:

    • A character-by-character bit mask of 8 or 16 binary digits, e.g. "XXVVVVXXX"
      In this case, the "V" bits denote a continuous bit field that contains the datum. For use in SplitVariableValue this mask can also be entered a a list of multiple bit masks, separated by spaces.
    • A small decimal value, i.e. "9"
      In this case, aka Radix mask, it forms the multiplier (N) which combines with the maximum value (maxVal, defined in a subclass) to break the CV into three parts:
      • lowest part, stored as 1 times a value 0-(N-1)
      • datum stored as datum*N (datum is limited to maxVal)
      • highest part, which stored as N*(maxVal+1) times the value
      As an example, consider storing two decimal digits as a decimal value. You can't use a bit mask changing the 2nd digit from 1 to 7, for example with a total value of 14 to 74, changes bits that are also used by the first digit. Instead, code this as
      • mask="1" maxVal="9"
      • mask="10" maxVal="9"
      and you'll get the desired effect. (This requires Schema xml/schema/decoder-4-15-2.xsd for validation)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.HashMap<java.lang.String,​CvValue> _cvMap
      A vector of CV objects used to look up CVs.
      protected javax.swing.JLabel _status
      Field holds the current status.
      protected java.lang.String _tooltipText
      Field holds the current tool tip text.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected VariableValue()
      Create a null object.
        VariableValue​(java.lang.String label, java.lang.String comment, java.lang.String cvName, boolean readOnly, boolean infoOnly, boolean writeOnly, boolean opsOnly, java.lang.String cvNum, java.lang.String mask, java.util.HashMap<java.lang.String,​CvValue> v, javax.swing.JLabel status, java.lang.String item)  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void confirmAll()
      Confirm the contents of this Variable.
      static boolean considerChanged​(CvValue c)
      Default implementation for subclasses to tell if a CV meets a common definition of "changed".
      java.lang.String cvName()
      Get the CV name.
      abstract void dispose()
      Dispose of the object.
      java.lang.String getComment()  
      abstract java.awt.Component getCommonRep()
      Get a display representation Object of this variable.
      java.lang.String getCvDescription()
      Provide a user-readable description of the CVs accessed by this variable.
      java.lang.String getCvName()  
      java.lang.String getCvNum()  
      boolean getInfoOnly()  
      abstract int getIntValue()
      Get the value as a single integer.
      long getLongValue()
      Get the value as an Unsigned Long.
      java.lang.String getMask()
      Extending classes should override to return a single mask in case a list of masks was provided and the class only uses one.
      protected static java.lang.String getMaxMask​(int maxVal)
      Create a "VVV" style mask matching the size of max value in bits.
      abstract java.awt.Component getNewRep​(java.lang.String format)
      Creates a new Object representation for display purposes, using the specified format.
      boolean getOpsOnly()  
      boolean getReadOnly()  
      AbstractValue.ValueState getState()  
      java.lang.String getTextValue()  
      protected int getValueInCV​(int Cv, java.lang.String maskString, int maxVal)
      Extract the current value from the CV, using the mask as needed.
      abstract java.lang.Object getValueObject()  
      abstract java.lang.String getValueString()  
      boolean getWriteOnly()  
      protected boolean isBitMask​(java.lang.String mask)
      Is this a bit mask (such as XVVVXXXX form) vs. radix mask (small integer)?
      boolean isBusy()
      Check if a variable is busy (during read, write operations).
      abstract boolean isChanged()
      Determine whether this Variable is "changed", so that "read changes" and "write changes" will act on it.
      boolean isToRead()
      Ask whether this object needs to be read.
      boolean isToWrite()
      Ask whether this object needs to be written.
      java.lang.String item()
      Gets the unique name for this Variable.
      java.lang.String label()
      Gets the displayed label for the Variable.
      protected int maskValAsInt​(java.lang.String maskString)
      Convert a String bit mask like XXXVVVXX to an int like 0b00011100.
      protected int offsetVal​(java.lang.String maskString)
      Find number of places to shift a value left to align it with a mask.
      abstract void propertyChange​(java.beans.PropertyChangeEvent e)  
      abstract java.lang.Object rangeVal()
      Gets a (usually text) description of the variable type and range.
      abstract void readAll()
      Always read the contents of this Variable.
      abstract void readChanges()
      Read the contents of this Variable if it's in a state that indicates it was "changed".
      protected void setBusy​(boolean newBusy)  
      abstract void setCvState​(AbstractValue.ValueState state)
      Propagate a state change here to the CVs that are related, which will in turn propagate back to here.
      abstract void setIntValue​(int i)
      Set the value from a single number.
      void setState​(AbstractValue.ValueState state)
      Sets the current state of the variable.
      void setToolTipText​(java.lang.String t)
      Set tooltip text to be used by both the "value" and representations of this Variable.
      void setToRead​(boolean state)
      Mark whether this object needs to be read.
      void setToWrite​(boolean state)
      Mark whether this object needs to be written.
      void setValue​(java.lang.String value)
      Set value from a String value.
      protected int setValueInCV​(int oldCv, int newVal, java.lang.String maskString, int maxVal)
      Insert a value into a CV, using the mask as needed.
      protected void simplifyMask()
      In case a set of masks was provided, at end of Ctor pick the first mask for implementing classes that use just one.
      (package private) void updatedTextField()
      This should be overridden by any implementation.
      protected javax.swing.JComponent updateRepresentation​(javax.swing.JComponent c)
      Add the proper tooltip text to a graphical rep before returning it, sets the visibility.
      abstract CvValue[] usesCVs()
      Provide access to CVs used by this Variable.
      abstract void writeAll()
      Always write the contents of this Variable.
      abstract void writeChanges()
      Write the contents of this Variable if it's in a state that indicates it was "changed".

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • _cvMap

        protected java.util.HashMap<java.lang.String,​CvValue> _cvMap
        A vector of CV objects used to look up CVs.

      • _status

        protected javax.swing.JLabel _status
        Field holds the current status.

      • _tooltipText

        protected java.lang.String _tooltipText
        Field holds the current tool tip text.

    • Constructor Detail

      • VariableValue

        public VariableValue​(java.lang.String label,
                     java.lang.String comment,
                     java.lang.String cvName,
                     boolean readOnly,
                     boolean infoOnly,
                     boolean writeOnly,
                     boolean opsOnly,
                     java.lang.String cvNum,
                     java.lang.String mask,
                     java.util.HashMap<java.lang.String,​CvValue> v,
                     javax.swing.JLabel status,
                     java.lang.String item)
        Parameters:
        label - the displayed label for the Variable
        comment - for information only, generally not displayed
        cvName - the name for the CV. Seems to be generally ignored and set to "".
        readOnly - true if the variable is to be readable-only
        infoOnly - true if the variable is to be for information only (a fixed value that is neither readable or writable)
        writeOnly - true if the variable is to be writable-only
        opsOnly - true if the variable is to be programmable in ops mode only
        cvNum - the CV number
        mask - a bit mask like XXXVVVXX (converts to a value like 0b00011100) or a series of masks separated by spaces
        v - a vector of CV objects used to look up CVs
        status - a field that holds the current status
        item - the unique name for this Variable
        See Also:
        VariableValue

      • VariableValue

        protected VariableValue()
        Create a null object. Normally only used for tests and to pre-load classes.

    • Method Detail

      • getCommonRep

        public abstract java.awt.Component getCommonRep()
        Get a display representation Object of this variable.

        The actual stored value of a variable is not the most interesting thing. Instead, you usually get an Object representation for display in a table, etc. Modification of the state of that object then gets reflected back, causing the underlying CV objects to change.
        Returns:
        the Object representation for display purposes

      • getNewRep

        public abstract java.awt.Component getNewRep​(java.lang.String format)
        Creates a new Object representation for display purposes, using the specified format.
        Parameters:
        format - a name representing
        Returns:
        an Object representation for display purposes

      • getValueString

        public abstract java.lang.String getValueString()
        Returns:
        String that can (usually) be interpreted as an integer

      • getValueObject

        public abstract java.lang.Object getValueObject()
        Returns:
        Value as a native-form Object

      • getTextValue

        public java.lang.String getTextValue()
        Returns:
        User-desired value, which may or may not be an integer

      • getCvDescription

        public java.lang.String getCvDescription()
        Provide a user-readable description of the CVs accessed by this variable.

        Default is a single CV number

        Returns:
        a user-readable description

      • setIntValue

        public abstract void setIntValue​(int i)
        Set the value from a single number.

        In some cases, e.g. speed tables, this will result in complex behavior, where setIntValue(getIntValue()) results in something unexpected.

        Parameters:
        i - the integer value to set

      • setValue

        public void setValue​(java.lang.String value)
        Set value from a String value.

        The current implementation is a stand-in. Note that e.g. Speed Tables don't use a single Int. The solution to that is to override this in complicated variable types.

        Since variable values can now be non-integer (text, long, hex etc.) we need a universally-usable method for setting values, such as default values in decoder definitions.

        In the long term we don't want to have this method failing silently. Subclasses that need silent failure should override this method.

        Parameters:
        value - the String value to set

      • getIntValue

        public abstract int getIntValue()
        Get the value as a single integer.

        In some cases, e.g. speed tables, this will result in complex behavior, where setIntValue(getIntValue()) results in something unexpected.

        Returns:
        the value as an integer

      • getLongValue

        public long getLongValue()
        Get the value as an Unsigned Long.

        Some subclasses (e.g. SplitVariableValue) store the value as a long rather than an integer. This method should be used in cases where such a class may be queried (e.g. by ArithmeticQualifier).

        If not overridden by a subclass, it will return an UnsignedLong conversion of the value returned by getIntValue().

        Returns:
        the value as a long

      • updatedTextField

        void updatedTextField()
        This should be overridden by any implementation.

      • readAll

        public abstract void readAll()
        Always read the contents of this Variable.

      • writeAll

        public abstract void writeAll()
        Always write the contents of this Variable.

      • confirmAll

        public void confirmAll()
        Confirm the contents of this Variable.

      • readChanges

        public abstract void readChanges()
        Read the contents of this Variable if it's in a state that indicates it was "changed".
        See Also:
        isChanged()

      • writeChanges

        public abstract void writeChanges()
        Write the contents of this Variable if it's in a state that indicates it was "changed".
        See Also:
        isChanged()

      • considerChanged

        public static boolean considerChanged​(CvValue c)
        Default implementation for subclasses to tell if a CV meets a common definition of "changed". This implementation will only consider a variable to be changed if the underlying CV(s) state is EDITED, e.g. if the CV(s) has been manually edited.
        Parameters:
        c - CV to be examined
        Returns:
        true if to be considered changed

      • propertyChange

        public abstract void propertyChange​(java.beans.PropertyChangeEvent e)
        Specified by:
        propertyChange in interface java.beans.PropertyChangeListener

      • dispose

        public abstract void dispose()
        Dispose of the object.

      • rangeVal

        public abstract java.lang.Object rangeVal()
        Gets a (usually text) description of the variable type and range.
        Returns:
        description of the variable type and range

      • label

        public java.lang.String label()
        Gets the displayed label for the Variable.
        Returns:
        the displayed label for the Variable

      • item

        public java.lang.String item()
        Gets the unique name for this Variable.
        Returns:
        the unique name for this Variable

      • cvName

        public java.lang.String cvName()
        Get the CV name.
        Returns:
        the name for the CV

      • setToolTipText

        public void setToolTipText​(java.lang.String t)
        Set tooltip text to be used by both the "value" and representations of this Variable.

        This is expected to be overridden in subclasses to change their internal info.

        Parameters:
        t - the tooltip text to be used
        See Also:
        updateRepresentation(javax.swing.JComponent)

      • updateRepresentation

        protected javax.swing.JComponent updateRepresentation​(javax.swing.JComponent c)
        Add the proper tooltip text to a graphical rep before returning it, sets the visibility.
        Parameters:
        c - the current graphical representation
        Returns:
        the updated graphical representation

      • getComment

        public java.lang.String getComment()
        Returns:
        the comment

      • getReadOnly

        public boolean getReadOnly()
        Returns:
        the value of the readOnly attribute

      • getInfoOnly

        public boolean getInfoOnly()
        Returns:
        the value of the infoOnly attribute

      • getWriteOnly

        public boolean getWriteOnly()
        Returns:
        the value of the writeOnly attribute

      • getOpsOnly

        public boolean getOpsOnly()
        Returns:
        the value of the opsOnly attribute

      • getCvNum

        public java.lang.String getCvNum()
        Returns:
        the CV number

      • getCvName

        public java.lang.String getCvName()
        Returns:
        the CV name

      • getMask

        public java.lang.String getMask()
        Extending classes should override to return a single mask in case a list of masks was provided and the class only uses one.
        Returns:
        the CV bitmask in the form XXXVVVXX

      • setToRead

        public void setToRead​(boolean state)
        Mark whether this object needs to be read.

        Simple implementation for the case of a single CV. Intended to be sufficient for many subclasses.

        Overrides:
        setToRead in class AbstractValue
        Parameters:
        state - true if the object needs to be read, false otherwise
        See Also:
        AbstractValue

      • isToRead

        public boolean isToRead()
        Ask whether this object needs to be read.

        Simple implementation for the case of a single CV. Intended to be sufficient for many subclasses.

        Overrides:
        isToRead in class AbstractValue
        Returns:
        true if the object needs to be read, false otherwise
        See Also:
        AbstractValue

      • setToWrite

        public void setToWrite​(boolean state)
        Mark whether this object needs to be written.

        Simple implementation for the case of a single CV. Intended to be sufficient for many subclasses.

        Overrides:
        setToWrite in class AbstractValue
        Parameters:
        state - true if the object needs to be written, false otherwise
        See Also:
        AbstractValue

      • isToWrite

        public boolean isToWrite()
        Ask whether this object needs to be written.

        Simple implementation for the case of a single CV. Intended to be sufficient for many subclasses.

        Overrides:
        isToWrite in class AbstractValue
        Returns:
        true if the object needs to be written, false otherwise
        See Also:
        AbstractValue

      • setCvState

        public abstract void setCvState​(AbstractValue.ValueState state)
        Propagate a state change here to the CVs that are related, which will in turn propagate back to here.
        Parameters:
        state - the new state to set

      • isBusy

        public boolean isBusy()
        Check if a variable is busy (during read, write operations).
        Returns:
        true if busy

      • setBusy

        protected void setBusy​(boolean newBusy)
        Parameters:
        newBusy - the desired state

      • simplifyMask

        protected void simplifyMask()
        In case a set of masks was provided, at end of Ctor pick the first mask for implementing classes that use just one. Call not required if mask is ignored.

      • getMaxMask

        protected static java.lang.String getMaxMask​(int maxVal)
        Create a "VVV" style mask matching the size of max value in bits.
        Parameters:
        maxVal - the maximum value to be stored in the cv as decimal
        Returns:
        a string of V's

      • maskValAsInt

        protected int maskValAsInt​(java.lang.String maskString)
        Convert a String bit mask like XXXVVVXX to an int like 0b00011100.
        Parameters:
        maskString - the textual (XXXVVVXX style) mask
        Returns:
        the binary integer (0b00011100 style) mask

      • isBitMask

        protected boolean isBitMask​(java.lang.String mask)
        Is this a bit mask (such as XVVVXXXX form) vs. radix mask (small integer)?
        Parameters:
        mask - the bit mask to check
        Returns:
        true if XVVVXXXX form

      • offsetVal

        protected int offsetVal​(java.lang.String maskString)
        Find number of places to shift a value left to align it with a mask.

        For example, a mask of "XXVVVXXX" means that the value 5 needs to be shifted left 3 places before being masked and stored as XX101XXX

        Parameters:
        maskString - the (XXXVVVXX style) mask
        Returns:
        the number of places to shift left before masking

      • getValueInCV

        protected int getValueInCV​(int Cv,
                           java.lang.String maskString,
                           int maxVal)
        Extract the current value from the CV, using the mask as needed.
        Parameters:
        Cv - the full CV value of interest.
        maskString - the (XXXVVVXX style or small int) mask for extracting the Variable value from this CV
        maxVal - the maximum possible value for this Variable position in the CV. Note it's 10 (0-9) in a single digit using a radix mask.
        Returns:
        the current value of the Variable. Optional factor and offset not yet applied.

      • setValueInCV

        protected int setValueInCV​(int oldCv,
                           int newVal,
                           java.lang.String maskString,
                           int maxVal)
        Insert a value into a CV, using the mask as needed.
        Parameters:
        oldCv - Value of the CV before this update is applied
        newVal - Value for this variable (e.g. not the CV value). Optional factor and offset already applied.
        maskString - The (XXXVVVXX style or small int) mask for this variable in character form
        maxVal - the maximum possible value for this Variable
        Returns:
        int new value for the full CV

      • usesCVs

        public abstract CvValue[] usesCVs()
        Provide access to CVs used by this Variable.
        Returns:
        an array of CVs used by this Variable