Package jmri.jmrit.symbolicprog

Class VariableValue

java.lang.Object
jmri.jmrit.symbolicprog.AbstractValue
jmri.jmrit.symbolicprog.VariableValue
All Implemented Interfaces:
PropertyChangeListener, EventListener
Direct Known Subclasses:
ConstantValue, DecVariableValue, EnumVariableValue, LongAddrVariableValue, SpeedTableVarValue, SplitEnumVariableValue, SplitVariableValue
public abstract class VariableValue extends AbstractValue implements 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 Details

  • Constructor Details

    • VariableValue

      public VariableValue(String label, String comment, String cvName, boolean readOnly, boolean infoOnly, boolean writeOnly, boolean opsOnly, String cvNum, String mask, HashMap<String,CvValue> v, JLabel status, 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

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

  • Method Details

    • getCommonRep

      public abstract 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 Component getNewRep(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 String getValueString()
      Returns:
      String that can (usually) be interpreted as an integer

    • getValueObject

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

    • getTextValue

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

    • getCvDescription

      public 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(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:

    • 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

      public abstract boolean isChanged()
      Determine whether this Variable is "changed", so that "read changes" and "write changes" will act on it.
      Returns:
      true if Variable is "changed"
      See Also:

    • 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, or UNKNOWN.
      Parameters:
      c - CV to be examined
      Returns:
      true if to be considered changed

    • propertyChange

      public abstract void propertyChange(PropertyChangeEvent e)
      Specified by:
      propertyChange in interface PropertyChangeListener

    • dispose

      public abstract void dispose()
      Dispose of the object.

    • rangeVal

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

    • label

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

    • item

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

    • cvName

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

    • setToolTipText

      public void setToolTipText(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

      protected JComponent updateRepresentation(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 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 String getCvNum()
      Returns:
      the CV number

    • getCvName

      public String getCvName()
      Returns:
      the CV name

    • getMask

      public 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

    • getState

      public AbstractValue.ValueState getState()
      Returns:
      the current state of the Variable

    • setState

      public void setState(AbstractValue.ValueState state)
      Sets the current state of the variable.
      Parameters:
      state - the desired state as per definitions in AbstractValue
      See Also:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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 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(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(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(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, 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, 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