Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
indigo_5_documentation:variable_class [2012/01/05 22:05] – [Class Method] jayindigo_5_documentation:variable_class [2025/02/18 20:36] (current) – external edit 127.0.0.1
Line 1: Line 1:
 +====== Variables ======
 +
 +The variable class represents an Indigo variable.
 +
 +==== Class Properties ====
 +
 +^Property ^  Type  ^Description ^
 +|//''id''//|  integer  |the unique id of the variable, assigned on creation by IndigoServer|
 +|//''folderId''//|  integer  |the unique id of the folder this variable is in (0 if it's not in a folder) - use //''moveToFolder()''// method to change|
 +|//''name''//|  string  |the name of the variable - no two variable can have the same name|
 +|//''readOnly''//|  string  |is the variable read only - currently only the //''isDaylight''// variable is read only|
 +|//''remoteDisplay''//|  boolean  |should this variable be displayed in remote clients (IWS, Indigo Touch, etc)|
 +|//''value''//|  string  |the value of the variable|
 +
 +==== Class Method ====
 +
 +The Variable class has a special method, ''**getValue(TYPE, default=VALUE)**'', that you can call which will retrieve the variable value as the specified Python class. There are a couple of advantages to using this method: first, it won't throw an exception but will always return a value; second, the Indigo server will do the conversion in the exact same way that it does type conversions when using variables in triggers and conditions. You can also optionally specify a default value if the value can't be successfully converted into the specified type. Here's a list of the valid types you can specify and what the default is if not specified:
 +
 +^  Type Literal  ^  Type Returned  ^Default ^
 +|  bool  |  Boolean  |**''True''** will be returned if the value is one of these: "true", "on", "yes", and "1". ''**False**'' will be returned if the value is one of these: "false", "off", "no", and "0". If no default value is specified and the value can't be successfully converted, the method will return False.  |
 +|  int  |  Integer  |An integer object will be returned if the value is an integer number or a float/decimal. In the latter case, the number will be rounded to the nearest integer. If no default value is specified and the value can't be converted, the method will return 0 |
 +|  float  |  Float  |A float object will be returned if the value is a float/decimal or an integer. If no default value is specified and the value can't be converted, the method will return 0.0 |
 +
 +Remember that accessing the ''**value**'' property of a variable object (''//var.value//'') will return a string object so you don't need a conversion for that.
 +
 +=== Class Method Examples ===
 +<code># Get a variable
 +var = indigo.variables[123456]
 +
 +# Getting the boolean value
 +intValue = var.getValue(bool)   # False if it can't be converted
 +intValue = var.getValue(int, default=True) # True if it can't be converted
 +
 +# Getting the integer value
 +intValue = var.getValue(int)   # 0 if it can't be converted
 +intValue = var.getValue(int, default=10) # 10 if it can't be converted
 +
 +# Getting the float value
 +intValue = var.getValue(float)   # 0 if it can't be converted
 +intValue = var.getValue(float, default=98.6) # 98.6 if it can't be converted
 +</code>
 +==== Commands (indigo.variable.*) ====
 +
 +=== Create ===
 +
 +Create a variable. This method returns a **copy** of the newly created variable.
 +
 +^  Command Syntax Examples  ^
 +|<code>indigo.variable.create("VariableName", value="Var Value", folder=843920)</code>|
 +
 +^  Parameters  ^^^^
 +^  Parameter  ^  Required  ^  Type  ^  Description  ^
 +|//''folder''//|  No  |  integer  |id or instance of the folder in which to put the newly created device - defaults to 0 (no folder)|
 +|//''name''//|  Yes  |  string  |the name of the variable|
 +|//''value''//|  No  |  string  |the value of the variable|
 +
 +=== Delete ===
 +
 +Delete the specified folder.
 +
 +^  Command Syntax Examples  ^
 +|<code>indigo.variable.delete(123)</code>|
 +
 +^  Parameters  ^^^^
 +^  Parameter  ^  Required  ^  Type  ^  Description  ^
 +|direct parameter|  Yes  |  integer  |id or instance of the variable to delete|
 +
 +=== Duplicate ===
 +
 +Duplicate the specified variable. This method returns a copy of the new variable.
 +
 +^  Command Syntax Examples  ^
 +|<code>indigo.variable.duplicate(123, duplicateName="NewName")</code>|
 +
 +^  Parameters  ^^^^
 +^  Parameter  ^  Required  ^  Type  ^  Description  ^
 +|direct parameter|  Yes  |  integer  |id or instance of the variable to duplicate|
 +|//''duplicateName''//|  No  |  string  |name for the newly duplicated variable|
 +
 +=== Move To Folder ===
 +
 +Use this command to move the variable to a different folder.
 +
 +^  Command Syntax Examples  ^
 +|<code>indigo.variable.moveToFolder(123, value=987)</code>|
 +
 +^  Parameters  ^^^^
 +^  Parameter  ^  Required  ^  Type  ^  Description  ^
 +|direct parameter|  Yes  |  integer  |id or instance of the variable|
 +|//''value''//|  Yes  |  integer  |id or instance of the folder to move the variable to|
 +
 +=== Set Remote Display ===
 +
 +Use this command to set the remote display flag for the folder.
 +
 +^  Command Syntax Examples  ^
 +|<code>indigo.variable.displayInRemoteUI(123, value=True)</code>|
 +
 +^  Parameters  ^^^^
 +^  Parameter  ^  Required  ^  Type  ^  Description  ^
 +|direct parameter|  Yes  |  integer  |id or instance of the variable|
 +|//''value''//|  Yes  |  boolean  |True to display the variable on remote user interfaces or False to hide it|
 +
 +=== Update Value ===
 +
 +Use this command to set the value of a variable without having to get a local copy first.
 +
 +^  Command Syntax Examples  ^
 +|<code>indigo.variable.updateValue(123, value="New Value")</code>|
 +
 +^  Parameters  ^^^^
 +^  Parameter  ^  Required  ^  Type  ^  Description  ^
 +|direct parameter|  Yes  |  integer  |id or instance of the variable|
 +|//''value''//|  Yes  |  string  |the new value for the variable|
 +
 +==== Examples ====
 +
 +^  Python  ^  AppleScript  ^
 +|<code># Create a new variable
 +newVar = indigo.variable.create("fooName", "fooMonster")
 +
 +# Updating value via command space function:
 +indigo.variable.updateValue(newVar, "asleep789")
 +newVar.refreshFromServer()  # refresh needed to update local's .value
 +
 +# changing name property
 +newVar.name = "goodName"
 +newVar.replaceOnServer()
 +
 +newVar.name = "bad name"  # should throw because of space character
 +
 +# changing name and values properties:
 +newVar.name = "goodName2"
 +newVar.value = "searchingForWaldo"
 +newVar.replaceOnServer()
 +
 +indigo.variable.delete(newVar)
 +
 +# Getting a variable using it's ID
 +someVar = indigo.variables[123]
 +
 +# Getting a variable using it's name
 +someVar = indigo.variables["MyVarName"]</code>|<code>-- Create a new variable
 +set newVar to make new variable with properties {name:"fooName", value:"fooMonster"}
 +
 +-- Update value
 +set value of newVar to "asleep789"
 +
 +
 +-- Changing name property
 +set name of newVar to "goodName"
 +set newVar to variable "goodName" -- when the name changes, you have to get a fresh reference
 +
 +set name of newVar to "bad name" -- should error because of space character
 +
 +-- Changing name and values properties
 +set name of newVar to "goodName2"
 +set newVar to variable "goodName2" -- when the name changes, you have to get a fresh reference
 +set value of newVar to "searchingForWaldo"
 +
 +delete variable "goodName2"
 +
 +# You can't get a variable using its ID in AppleScript
 +
 +
 +# Getting a variable using it's name
 +set someVar to variable named "MyVarName"</code>|