Class VariableValue
- java.lang.Object
-
- jmri.jmrit.symbolicprog.AbstractValue
-
- jmri.jmrit.symbolicprog.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
- mask="1" maxVal="9"
- mask="10" maxVal="9"
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class jmri.jmrit.symbolicprog.AbstractValue
AbstractValue.ValueState
-
-
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.-
Fields inherited from class jmri.jmrit.symbolicprog.AbstractValue
prop
-
-
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 representationObject
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 newObject
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 jmri.jmrit.symbolicprog.AbstractValue
addPropertyChangeListener, getAvailable, removePropertyChangeListener, setAvailable, setColor
-
-
-
-
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 Variablecomment
- for information only, generally not displayedcvName
- the name for the CV. Seems to be generally ignored and set to "".readOnly
- true if the variable is to be readable-onlyinfoOnly
- 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-onlyopsOnly
- true if the variable is to be programmable in ops mode onlycvNum
- the CV numbermask
- a bit mask like XXXVVVXX (converts to a value like 0b00011100) or a series of masks separated by spacesv
- a vector of CV objects used to look up CVsstatus
- a field that holds the current statusitem
- 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 representationObject
of this variable.
The actual stored value of a variable is not the most interesting thing. Instead, you usually get anObject
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 newObject
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 along
rather than aninteger
. This method should be used in cases where such a class may be queried (e.g. byArithmeticQualifier
).If not overridden by a subclass, it will return an
UnsignedLong
conversion of the value returned bygetIntValue()
.- 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()
-
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(jmri.jmrit.symbolicprog.CvValue)
-
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 interfacejava.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
-
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:
AbstractValue
-
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 classAbstractValue
- 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 classAbstractValue
- 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 classAbstractValue
- 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 classAbstractValue
- 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 CVmaxVal
- 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 appliednewVal
- 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 formmaxVal
- the maximum possible value for this Variable- Returns:
- int new value for the full CV
-
-