com.SIMRacingApps

Class Gauge

java.lang.Object

com.SIMRacingApps.Gauge

Direct Known Subclasses:

iRacingGauge

public class Gauge
extends java.lang.Object

The Gauge class is used to monitor anything on the car that has a value, or has a value that can be set on the next pit stop. It will have 3 possible values, Current, Next, Historical. A flag for each of the values so you know when they get updated.

    Current    = (real-time, pit stall)
    Next       = (fixed, real-time, pit stall)
    Historical = The value of Current stored by lap when measured in the pit stall.
 

A Change Flag to indicate you want to apply the Next value at the next valid change point (real-time,pit stall). Changing the Next value will automatically set the Dirty Flag and the Change Flag if not equal Current.

It will have Capacity Minimum,Maximum and Increment values that will constrain what you can change the Next value to. It will have Minimum and Maximum values that a gauge would display. It will have Major and Minor Increments that can be used by a gauge for display.

A gauge doesn't have to be on the car, it could be in the pits (such as a tire pressure or temperature gauge). A gauge could represent an object that gets replaced when pitting or when reset that may not output a value (such as the wind-shield tear-off).

A gauge can have several attributes to allow clients to build adaptable software representations of a gauge. It has min and max values on the gauge. It has min and max values(capacity) that it can have. It has an increment that all values will be rounded to when changing it.

A gauge can also have "State", which is defined range(s) of values. Standard States are "NOTAVAILABLE", "OFF", "ERROR" and "NORMAL". Clients can choose to display different colors, blink, or other visual effects based on the state. Many gauges also have additional states. See Gauge.Type for each gauges documentation for the states it supports.

Since:

1.4

Author:

Jeffrey Gilliam

Copyright:

Copyright (C) 2015 - 2024 Jeffrey Gilliam

License:

Apache License 2.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Gauge.Type This defines all the possible gauge types.

Constructor Summary

Constructors

Constructor and Description
Gauge(java.lang.String type, Car car, Track track, java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Object>>> simGaugesBefore, java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Object>>> simGaugesAfter) Constructor for the Gauge class.

Method Summary

Modifier and Type	Method and Description
void	_addStateRange(Gauge gauge) Adds all the states from the passed in gauge to this gauge.
void	_addStateRange(java.lang.String stateName, java.lang.String name, double start, double end, java.lang.String UOM)
void	_addStateRange(java.lang.String stateName, java.lang.String name, double start, double end, java.lang.String UOM, Data d)
void	_removeStateRange(java.lang.String stateName, java.lang.String name)
Data	_setCapacityIncrement(double d, java.lang.String uom)
Data	_setCapacityMaximum(double d, java.lang.String uom)
Data	_setCapacityMinimum(double d, java.lang.String uom)
Data	_setIsChangable(boolean b)
Data	_setIsDirty(boolean b)
Data	_setIsFixed(boolean b)
Data	_setMajorIncrement(double d, java.lang.String uom)
Data	_setMaximum(double d, java.lang.String uom)
Data	_setMinimum(double d, java.lang.String uom)
Data	_setMinorIncrement(double d, java.lang.String uom)
Data	_setOnResetChange(boolean b)
Data	decrementValueNext()
Data	decrementValueNext(java.lang.String UOM) Decrements the next value, to be applied at the next pit stop, according to the value set by _setCapacityIncrement(double,String).
Data	getCapacityIncrement()
Data	getCapacityIncrement(java.lang.String UOM) Returns the increment value that the gauge uses when you call incrementValueNext(String) or decrementValueNext(String).
Data	getCapacityMaximum()
Data	getCapacityMaximum(java.lang.String UOM) Returns the maximum number that this gauge will accept when calling setValueNext(double,String) or incrementValueNext(String)
Data	getCapacityMaximumRaw()
Data	getCapacityMinimum()
Data	getCapacityMinimum(java.lang.String UOM) Returns the minimum number that this gauge will accept when calling setValueNext(double,String) or decrementValueNext(String)
Data	getCapacityMinimumRaw()
Data	getChangeFlag() Returns Y if the object for this gauge is flagged for changed on the next pit stop.
Data	getCount() Returns the number of times this gauge was used.
Data	getIsChangeable() Returns true if this gauge represents an object that can be replaced/changed at the next pit stop (i.e.
Data	getIsDirty() Returns Y if the next value of the gauge is different from the current value.
Data	getIsFixed() Returns false if this gauge's next value can be changed via setValueNext(double,String), incrementValueNext(String) or decrementValueNext(String).
Data	getLapChanged() Returns the lap when the object for this gauge was changed.
Data	getLaps()
Data	getLaps(int currentLap) Returns the number of laps since the object for this gauge was changed.
Data	getLaps(java.lang.String currentLap)
Data	getLapsHistorical() Returns the number of laps since the last change.
Data	getMajorIncrement()
Data	getMajorIncrement(java.lang.String UOM) Returns how often to show major tick marks between the minimum and the maximum.
Data	getMaxCount() Returns the number of times this gauge can be changed.
Data	getMaximum()
Data	getMaximum(java.lang.String UOM) Returns the maximum value of where this gauge should end with the last tick mark (i.e.
Data	getMinimum()
Data	getMinimum(java.lang.String UOM) Returns the minimum value of where this gauge should start with the first tick mark (i.e.
Data	getMinorIncrement()
Data	getMinorIncrement(java.lang.String UOM) Returns how often to show minor tick marks between the minimum and the maximum.
Data	getMultiplier() Return a multiplier to be used when calculating the major and minor tick marks.
Data	getName() Returns the untranslated name to display on the gauge.
Data	getOnResetChange() Returns true if this gauge is changed on a reset.
Data	getType() Returns the type of gauge as defined by Gauge.Type
Data	getTypeName() Returns farther explanation of the gauge (i.e.
Data	getUOM() Returns the Unit of Measure for this gauge (i.e.
Data	getValueCurrent()
Data	getValueCurrent(java.lang.String UOM) Returns the current value of the gauge.
Data	getValueHistorical()
Data	getValueHistorical(java.lang.String UOM) Returns the historical value of the gauge taken at the time it was changed.
Data	getValueNext()
Data	getValueNext(java.lang.String UOM) Returns the value of the next value that the object will be at the next pit stop.
Data	incrementValueNext()
Data	incrementValueNext(java.lang.String UOM) Increments the next value, to be applied at the next pit stop, according to the value set by _setCapacityIncrement(double,String).
Data	setChangeFlag(boolean flag) Sets the change flag for this gauge and all the gauges grouped with it.
Data	setChangeFlag(java.lang.String flag)
Data	setValueNext()
Data	setValueNext(double value, java.lang.String UOM) Sets the next value to be applied at the next pit stop.
Data	setValueNext(java.lang.String value)
Data	setValueNext(java.lang.String value, java.lang.String UOM)
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Gauge

public Gauge(java.lang.String type,
             Car car,
             Track track,
             java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Object>>> simGaugesBefore,
             java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Object>>> simGaugesAfter)

Constructor for the Gauge class. Some gauges change depending on the track. The UOM will be set my the SIM to either what is naturally displayed on this car at this track. Or, it could let the user switch between Imperial and Metric.

Parameters:

type - The type of gauge as defined by Gauge.Type

car - The car to associate this gauge with.

track - The track the car will be running on.

simGaugesBefore - A map that contains gauge data from the SIM to be applied first. The files can then override those values if needed.

simGaugesAfter - A map that contains gauge data from the SIM to be applied after the files are processed to override any values in them.

Method Detail

getType

public Data getType()

Returns the type of gauge as defined by Gauge.Type

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/Type

Returns:

the type of gauge

getName

public Data getName()

Returns the untranslated name to display on the gauge. (e.g. WATER)

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/Name

Returns:

The name of the gauge.

getTypeName

public Data getTypeName()

Returns farther explanation of the gauge (i.e. TEMP)

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/TypeName

Returns:

A additional explanation of the gauge.

getUOM

public Data getUOM()

Returns the Unit of Measure for this gauge (i.e. "F") based on the users locale. This may not be the same as the internal UOM that is what all the values are in. All the values are converted to this UOM before returning them.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/UOM

Returns:

The Unit of Measure.

getMultiplier

public Data getMultiplier()

Return a multiplier to be used when calculating the major and minor tick marks. For example: the tachometer returns values in RPMs ranging from 0 to 11,000. The multiplier could be set to .001, so that the gauge major tick marks go from 0 to 11.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/Multiplier

Returns:

The multiplier value.

getMinimum

public Data getMinimum(java.lang.String UOM)

Returns the minimum value of where this gauge should start with the first tick mark (i.e. 0) Note: The value would be after the multiplier has been applied.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/Minimum/(UOM)

Parameters:

UOM - (Optional) The UOM to convert the value to, defaults to the gauge's UOM.

Returns:

The minimum value

getMinimum

public Data getMinimum()

getMaximum

public Data getMaximum(java.lang.String UOM)

Returns the maximum value of where this gauge should end with the last tick mark (i.e. 300). Note: The value would be after the multiplier has been applied.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/Maximum/(UOM)

Parameters:

UOM - (Optional) The UOM to convert the value to, defaults to the gauge's UOM.

Returns:

The maximum value

getMaximum

public Data getMaximum()

getMajorIncrement

public Data getMajorIncrement(java.lang.String UOM)

Returns how often to show major tick marks between the minimum and the maximum. Note: The value would be after the multiplier has been applied.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/MajorIncrement/(UOM)

Parameters:

UOM - (Optional) The UOM to convert the value to, defaults to the gauge's UOM.

Returns:

The major increment value

getMajorIncrement

public Data getMajorIncrement()

getMinorIncrement

public Data getMinorIncrement(java.lang.String UOM)

Returns how often to show minor tick marks between the minimum and the maximum. Note: The value would be after the multiplier has been applied.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/MinorIncrement/(UOM)

Parameters:

UOM - (Optional) The UOM to convert the value to, defaults to the gauge's UOM.

Returns:

The minor increment value

getMinorIncrement

public Data getMinorIncrement()

getCapacityMaximum

public Data getCapacityMaximum(java.lang.String UOM)

Returns the maximum number that this gauge will accept when calling setValueNext(double,String) or incrementValueNext(String)

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/CapacityMaximum/(UOM)

Parameters:

UOM - (Optional) The UOM to convert the value to, defaults to the gauge's UOM.

Returns:

The maximum capacity.

getCapacityMaximum

public Data getCapacityMaximum()

getCapacityMaximumRaw

public Data getCapacityMaximumRaw()

getCapacityMinimum

public Data getCapacityMinimum(java.lang.String UOM)

Returns the minimum number that this gauge will accept when calling setValueNext(double,String) or decrementValueNext(String)

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/CapacityMinimum/(UOM)

Parameters:

UOM - (Optional) The UOM to convert the value to, defaults to the gauge's UOM.

Returns:

The minimum capacity.

getCapacityMinimum

public Data getCapacityMinimum()

getCapacityMinimumRaw

public Data getCapacityMinimumRaw()

getCapacityIncrement

public Data getCapacityIncrement(java.lang.String UOM)

Returns the increment value that the gauge uses when you call incrementValueNext(String) or decrementValueNext(String). Also, all values passed to setValueNext(double,String) are rounded up to the the closest multiple of this value.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/CapacityIncrement/(UOM)

Parameters:

UOM - (Optional) The UOM to convert the value to, defaults to the gauge's UOM.

Returns:

The incremental capacity.

getCapacityIncrement

public Data getCapacityIncrement()

getIsFixed

public Data getIsFixed()

Returns false if this gauge's next value can be changed via setValueNext(double,String), incrementValueNext(String) or decrementValueNext(String). A client could use this value to grey out or hide the buttons for changing it.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/IsFixed

Returns:

true if gauge is fixed, false of not.

getIsChangeable

public Data getIsChangeable()

Returns true if this gauge represents an object that can be replaced/changed at the next pit stop (i.e. Tires, Tearoff usually)

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/IsChangeable

Returns:

true if gauge is changeable, false of not.

getOnResetChange

public Data getOnResetChange()

Returns true if this gauge is changed on a reset.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/OnResetChange

Returns:

true if gauge is changed on a reset, false of not.

getIsDirty

public Data getIsDirty()

Returns Y if the next value of the gauge is different from the current value.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/IsDirty

Returns:

Y if dirty, N if not.

getValueCurrent

public Data getValueCurrent(java.lang.String UOM)

Returns the current value of the gauge.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/ValueCurrent/(UOM)

Parameters:

UOM - (Optional) The unit of measure to return, default to the gauges UOM.

Returns:

The current value.

getValueCurrent

public Data getValueCurrent()

getLapChanged

public Data getLapChanged()

Returns the lap when the object for this gauge was changed.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/LapChanged

Returns:

The lap it was changed.

getCount

public Data getCount()

Returns the number of times this gauge was used.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/Count 1.2

Returns:

The number of times this gauge was changed.

Since:

1.2

getMaxCount

public Data getMaxCount()

Returns the number of times this gauge can be changed. By default, a gauge will return the NOTAVAILABLE status unless a specific gauge overrides it.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/MaxCount 1.13

Returns:

The number of times this gauge can be changed.

Since:

1.13

getLaps

public Data getLaps(int currentLap)

Returns the number of laps since the object for this gauge was changed. By default, a gauge will return the NOTAVAILABLE status unless a specific gauge overrides it.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/Laps/(CURRENTLAP)

Parameters:

currentLap - (Optional) The lap you are currently on, defaults to current lap.

Returns:

The number of laps.

getLaps

public Data getLaps(java.lang.String currentLap)

getLaps

public Data getLaps()

getValueHistorical

public Data getValueHistorical(java.lang.String UOM)

Returns the historical value of the gauge taken at the time it was changed.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/ValueHistorical/(UOM)

Parameters:

UOM - (Optional) The unit of measure to return it in, defaults to the gauges UOM.

Returns:

The historical value.

getValueHistorical

public Data getValueHistorical()

getLapsHistorical

public Data getLapsHistorical()

Returns the number of laps since the last change.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/LapsHistorical

Returns:

The lap number of laps since the last change.

getValueNext

public Data getValueNext(java.lang.String UOM)

Returns the value of the next value that the object will be at the next pit stop. By default it returns the current value.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/ValueNext/(UOM)

Parameters:

UOM - The unit of value to return.

Returns:

The value if the next value.

getValueNext

public Data getValueNext()

getChangeFlag

public Data getChangeFlag()

Returns Y if the object for this gauge is flagged for changed on the next pit stop.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/ChangeFlag

Returns:

Y if flagged for changed, N if not.

setChangeFlag

public Data setChangeFlag(boolean flag)

Sets the change flag for this gauge and all the gauges grouped with it. By default, this will not all the change flag to be true. Therefore, each gauge that can be changed, must override this and set the flag.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/setChangeFlag/(FLAG)

Parameters:

flag - Y or N to change or not to change

Returns:

The change flag

setChangeFlag

public Data setChangeFlag(java.lang.String flag)

decrementValueNext

public Data decrementValueNext(java.lang.String UOM)

Decrements the next value, to be applied at the next pit stop, according to the value set by _setCapacityIncrement(double,String). If the gauge is fixed, then only the change flag will be set and the next value will not be changed. The change flag is set to Y even if the new value and the old value are the same.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/decrementValueNext/(UOM)

Parameters:

UOM - (Optional) The unit of measure to return the new value in. Default gauge's UOM.

Returns:

The new value.

decrementValueNext

public Data decrementValueNext()

incrementValueNext

public Data incrementValueNext(java.lang.String UOM)

Increments the next value, to be applied at the next pit stop, according to the value set by _setCapacityIncrement(double,String). If the gauge is fixed, then only the change flag will be set and the next value will not be changed. If increments above the maximum capacity, then it sets it to the maximum capacity. The change flag is set to Y even if the new value and the old value are the same.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/incrementValueNext/(UOM)

Parameters:

UOM - (Optional) The unit of measure to return the new value in. Default to gauge's UOM.

Returns:

The new value.

incrementValueNext

public Data incrementValueNext()

setValueNext

public Data setValueNext(double value,
                         java.lang.String UOM)

Sets the next value to be applied at the next pit stop. If the gauge is fixed, then only the change flag will be set and the next value will not be changed. If below the minimum capacity, then it sets it to the minimum capacity. If above the maximum capacity, then it sets it to the maximum capacity. The value is rounded to the nearest increment as defined by _setCapacityIncrement(double,String). The change flag is set to Y even if the new value and the old value are the same.

PATH = /Car/(CARIDENTIFIER)/Gauge/(GAUGETYPE)/setValueNext/(VALUE)/(UOM)

Parameters:

value - (Optional) The value to be set. Default 0.

UOM - (Optional) The unit of measure the new measure to be set is in. Also affects return value. Default to gauge's UOM.

Returns:

The new value, possibly adjusted.

setValueNext

public Data setValueNext(java.lang.String value,
                         java.lang.String UOM)

setValueNext

public Data setValueNext(java.lang.String value)

setValueNext

public Data setValueNext()

_addStateRange

public void _addStateRange(Gauge gauge)

Adds all the states from the passed in gauge to this gauge.

Parameters:

gauge - The gauge to copy the states from

_addStateRange

public void _addStateRange(java.lang.String stateName,
                           java.lang.String name,
                           double start,
                           double end,
                           java.lang.String UOM)

_addStateRange

public void _addStateRange(java.lang.String stateName,
                           java.lang.String name,
                           double start,
                           double end,
                           java.lang.String UOM,
                           Data d)

_removeStateRange

public void _removeStateRange(java.lang.String stateName,
                              java.lang.String name)

_setMinimum

public Data _setMinimum(double d,
                        java.lang.String uom)

_setMaximum

public Data _setMaximum(double d,
                        java.lang.String uom)

_setMajorIncrement

public Data _setMajorIncrement(double d,
                               java.lang.String uom)

_setMinorIncrement

public Data _setMinorIncrement(double d,
                               java.lang.String uom)

_setCapacityMinimum

public Data _setCapacityMinimum(double d,
                                java.lang.String uom)

_setCapacityMaximum

public Data _setCapacityMaximum(double d,
                                java.lang.String uom)

_setCapacityIncrement

public Data _setCapacityIncrement(double d,
                                  java.lang.String uom)

_setIsFixed

public Data _setIsFixed(boolean b)

_setIsChangable

public Data _setIsChangable(boolean b)

_setIsDirty

public Data _setIsDirty(boolean b)

_setOnResetChange

public Data _setOnResetChange(boolean b)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object