VSPair

This is the VSPair object, which is used to describe a single value/status relationship or a range of values and associated status relationship. Multiples of these objects can be associated with a device to handle different types of control or status operations. Most of the modification of these pairs is done using the HomeSeer scripting/application interface commands that start with DeviceVSP_

CODE

    Public Class VSPair

        Public PairType As VSVGPairType
        Public Render_Location As Enums.CAPIControlLocation
        Public RangeStart As Double
        Public RangeEnd As Double
        Public RangeStatusPrefix As String = ""
        Public RangeStatusSuffix As String = ""
        Public RangeStatusDecimals As Integer = 0
        Public RangeStatusDivisor As Double = 0
        Public IncludeValues As Boolean = True
        Public ValueOffset As Double = 0
        Public HasAdditionalData As Boolean = False
        Public HasScale As Boolean = False
        Public ZeroPadding As Boolean = False
        Public Const ScaleReplace As String = "@S@"
        Public Shared Function AddDataReplace(ByVal Index As Integer) As String
        Public ReadOnly Property ControlStatus As ePairStatusControl
        Public Property Render As Enums.CAPIControlType
        Public PairButtonImageType As Enums.CAPIControlButtonImage
        Public PairButtonImage As String
        Public WriteOnly Property Status As String
        Public Property Value As Double
        Public Property StringList As String()
        Public WriteOnly Property StringListAdd As String
        Public Property ControlUse As ePairControlUse

    End Class

The definition for each member is as follows:

Name	Structure Member	Description
PairType		This enum indicates whether the pair represents a single value or a range of values.
Render_Location.	Row	If this is a control pair that is set to be rendered as a button, then set this to the row number to position the button at. Row or Column of 0 results in the button not being drawn, but the control option still exists.
Render_Location.	Column	If this is a control pair that is set to be rendered as a button, then set this to the column number to position the button at. Row or Column of 0 results in the button not being drawn, but the control option still exists.
Render_Location.	ColumnSpan	For more exact positioning of rendered controls on a device, you may indicate that a rendered control is to use multiple columns, thus allowing for alignment options. Note that not all 3rd party User Interfaces will be able to honor Row, Column, and ColumnSpan settings.
RangeStart		If this VSPair is a range, this contains the lowest value of the range being specified.
RangeEnd		If this VSPair is a range, this contains the highest value of the range being specified.
Value		If this VSPair is a single value pair and not a range, then this holds the value that this pair represents.
RangeStatusPrefix RangeStatusSuffix		These contain strings of text to be prepended (prefix) or appended (suffix) to the status string value as it is generated for a range value/status pair. These are not used for single-value pairs. An example of their use is in the range 1 to 99 to represent dim values, the prefix would be set to "Dim " and the suffix to "%", for a net status string when the value is 49 of "Dim 49%".
Status		When the value/status pair is not a range, this holds the status string to be displayed when the device is at the value set by the Value property.
RangeStatusDecimals		For range type value/status pairs, you may set this to a value > 0 to have that many decimal places displayed in the value. For example, if the range is 1 to 10, and the RangeStatusDecimals is set to 1, then the full range would encompass values such as: 1.0, 1.1, 1.2, 1.3.... 9.8, 9.9, 10.
RangeStatusDivisor		For range type value/status pairs, it may be inconvenient to modify the value so that it fits a more user-friendly display without messing up what the user has to enter for device value triggers - in that scenario, if you force the value to be 100 to represent 100K, the user may think they can enter 100 for a trigger when they need to enter 100000. To deal with this, set this property to 1000 and HomeSeer will divide the value by 1000 prior to formatting the display status string - the actual value will not be changed.
IncludeValues		For range value/status pairs, it is sometimes inconvenient having the value as part of the status when it is not indicative of anything meaningful. If IncludeValues is set to False, the status string generated will not include the values. Example: For a device which has an invalid state on values in the range 101 to 254, turn IncludeValues off (set it False) and set your RangeStatusPrefix to "INVALID VALUE", and that will cause HomeSeer to display INVALID VALUE for each of those values without having to use single value, value-status pairs.
ValueOffset		When it is desireable to have separate status and control value/status pair ranges, this property can be used to facilitate that since two separate status and control pairs cannot be for the same value. To use this, establish one range to use the true values of 1 to 100. Now, establish a second range to use the "fake" values of 101 to 200, but set the ValueOffset to 100, which causes HomeSeer to use a display status string with the value having 100 subtracted from it. For example, if you have a status range pair which creates a status of "Setting Is Currently 50" with a value of 50, you can have a control pair that creates a control option of "Set to 50 Degrees", which corresponds to the value 150. When a script or plug-in receives notification of the device changing to 150, the appropriate command can be sent to invoke the change to 50, and then the device may be set to 50 to indicate that the change has been made.
HasScale ScaleReplace		At the time a device is created, it may not be known whether its scale is meters or Miles, Fahrenheit or Celcius, or some other set of multiple scales. To help with those situations, set HasScale to True, use the constant ScaleReplace in your range prefix or suffix, and then at runtime when the device is being updated to a new value, set the device ScaleText to your scale (e.g. "degF" or "degC"), set the value, and then when the status is requested, HomeSeer will replace ScaleReplace (@S@) with your ScaleText.
ZeroPadding		When the status is rendered and a RangeStatusDecimals (decimal places) are specified, setting this to True will cause trailing zeros to be padded to the end of the value so that it always displays the number of decimal places desired. For example, with RangeStatusDecimals set to 3, the value 1.5 displays as 1.5 when ZeroPadding is False, and it displays as 1.500 when ZeroPadding is True.
HasAdditionalData AddDataReplace		The usage of these two properties is identical to that of HasScale/ScaleReplace except that you can use a virtually limitless number of replacements in the status string. To use, set HasAdditionalData to True, and then when the device is updated, set the device's AdditionalDisplayData (array of string) to the values that you want replaced. AddDataReplace is a shared (constant) function that can be used to generate a replacement variable for any number - for example, AddDataReplace with an argument value of 4 will return a replacement variable of "@%4@" (without quotes). If your range prefix or suffix contains this string (which you can use by calling AddDataReplace(4) when you are setting up the prefix or suffix), then that string will be replaced with the 4th value from the array of strings set on the device's AdditionalDisplayData property. e.g.: pair.HasAdditionalData = True pair.RangeStatusSuffix = AddDataReplace(0) & " of " & AddDataReplace(1) (Device value changes and becomes 5555...) Dim AddData(1) As String AddData(0) = "Miles" AddData(1) = "Asphalt" dv.AdditionalDisplayData(hs) = AddData hs.SetDeviceValue(MyDevice, 5555) Result: 5555 Miles of Asphalt
ControlStatus		This read-only property allows you to retrieve an Enum value indicating whether the pair is designated as being for status only, control only, or both status and control. Use the hs.DeviceVSP_ChangePair (and other functions) to set or change the ControlStatus.
ControlUse		This property is valid only if the ControlStatus is set to Control or Both, and is used to indicate, most appropriately for lighting control devices, which control pairs are for On, Off, or Dim control of a light. An option exists for On_Alternate so that devices supporting multiple "On" methods may indicate secondary On control values. The "Dim" ControlUse value should be used on any/all pairs which are levels between fully on and completely off.
Render		This property is used to get or set how the control status/value pair is to be rendered when control options are offered by a user interface. See the values under the CAPIControl/CAPIControlType topic.
PairButtonImageType		This value, which is only valid when the render type is Button, specifies if a graphics file should be used when the button is rendered on the HTML interface. The possible values are in Enums.CAPIControlButtonImage .
PairButtonImage		This value, which is only valid when the render type is Button AND the PairButtonImageType is Custom, should be set to the path - relative to the HTML directory - for the graphic image file to be used when the button is rendered on the HTML interface.
StringList StringListAdd		When the UI Render type is set to a drop-down list of strings, set StringList to the array of string values to be displayed. You may add the items one at a time using StringListAdd, or may set them all at once using StringList.