User Tools

Site Tools


dictionary:unitinformation:enumeratedvalue

Enumerated Value Of

Enumerated Value (optional: Of “Name of Unit”) (optional: for (integer value to get enumeration for))
returns string, or script error if value is out of range for available enumerations

The Enumerated Value Of verb returns a string equal to the enumerated value of a unit if available and in range or an apple script error if it is not. Examples of units that could be enumerated might be a thermostat mode unit which could be “off, heat, cool, auto,” a garage door unit that could be “open, closed” or a ceiling fan that might be “off, low, medium, medium-high, high”

The default parameter of the Unit Name is optional, if used in an ON or OFF script the current unit will be queried unless you specify a different name.

In XTension the enumerations are stored as a comma delimited string in the enumerated values field of the display tab in the edit unit dialog. They are also used as the values for the popup menu if that is selected as the default control type to present for the unit.

In this example a thermostat mode unit is queried for it’s enumerated value and then reset via another enumerated value. This lets you not have to know that with this particular interface or thermostat off is 0 and heat is 1 and cool is 2.

if (enumerated value of “thermostat mode unit”) = “cool” then
  write log "mode is ac, changing to heat"
  set value of “thermostat mode unit” to "heat"
end if

There is an optional parameter for which you can use to return the enumeration for a value other than the current value of the Unit.

write log “if the value was 2 then the enumeration would be “ & (enumerated value ofThe Unit” for 2)

this is particularly useful in the On and Off scripts of the Unit where you might wish to check the enumeration rather than the future value. Since the actual dictionary value of the Unit is not changed until AFTER the On script runs you cannot simply call enumerated value of in the ON script to get the NEW value, it will return the current value.

So in order to get the enumerated value of the future value use the verb like this:

write log “after this script the enumeration will be “ & enumerated value for (future value)

note that in the above since the script is running in the Units ON script it is not necessary to specify the name of the Unit. The thisUnit value will be used to make sure the enumeration comes from the Unit that owns the script.

History:

  • the enumerated value of verb was added in XTension version 9.4.36
  • optional “for” parameter added in XTension version 9.5.3
dictionary/unitinformation/enumeratedvalue.txt · Last modified: 2023/05/20 15:14 by James Sentman