This shows you the differences between two versions of the page.
Both sides previous revision Previous revision | |||
indigo_5_documentation:variable_class [2012/01/05 22:15] jay [Class Method] |
indigo_5_documentation:variable_class [2019/01/26 00:10] (current) |
||
---|---|---|---|
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 it's ID in AppleScript | ||
+ | |||
+ | |||
+ | # Getting a variable using it's name | ||
+ | set someVar to variable named "MyVarName"</code>| |