====== Bindings (variables) ====== For Lighting 12.5b1 and above. **Need to set "Expert mode" to on** ===== Purpose ===== Bindings are an easy way to animate items. Usually items properties are set with fixed values through the configuration screens. With bindings it is possible to use dynamic values for properties. Some use cases for bindings are: set the label of a shortcut with the time or cpu usage, set the position of an item according to the orientation, set an icon color using the battery level, move an item upon a swipe gesture, etc. A binding associates a value with a property. The value can be a single variable, or it can be an expression (with arithmetic computations for instance), or a complex script (with loops, functions and access to Lightning APIs). The property is an item's attribute to be set with the value. ===== How to create bindings ===== Turn "Expert mode" on first. Bindings are not shown in normal mode. Enter edit mode and select an item, then open the properties box (pencil icon in the bottom bar) and select the "Bindings" tab. This "Bindings" tab displays existing bindings. Tap on "Add binding..." to add a new one. You need to select a property, then set a value. Tap on OK to create the binding. A binding can be removed using the garbage icon on the right. A binding can be temporarily disabled by deselecting the "Enabled" checkbox on the left side. ==== Property ==== It is possible to select a property amongst the supported ones, in the following categories: * Position on the grid: cell position and dimension for the item on the grid * Position detached from the grid: free positioning and transformation (rotation, scale, etc.) * Item properties: generic properties for all item types (transparency, visibility, [[bindings_box|box]]) * Text: properties for items displaying some text (apps, shortcuts, folders, etc.). This can be the label, the font size, color, etc. * Icon: properties for items displaying an icon, such as icon scale, colorize filter. * Folder: properties for... folder! Such as window alignment. Not all attributes supported by Lightning are available as properties in bindings. The list of properties mainly includes visual attributes. Feel free to ask for more properties if needed! The box property, available from V12.5b7, is made of many "sub properties": margin, padding, border color and size, background color, for left/top/right/bottom side or normal/selected/focused states. Please refer to the [[bindings_box|box]] page for the box property syntax and how to use it. Things to be aware of: * When setting the item position and geometry, make sure that the item is attached to the grid when using cell properties, and make sure the item is detached when setting pixel positioning, rotation, scale, etc., otherwise changes are not visible. * In the item properties, the special "Dummy" property can be used to react to a variable change without actually changing any property. * Take care when setting the "Visibility" property. An invisible item is not clickable and can only be found using the items hierarchy menu. It can be difficult to locate an invisible item. ==== Variable ==== A variable is a piece of data kept by the launcher. There are two kinds of variables: * Builtin variables: such as screen size and orientation, cpu usage, battery level, etc. * User variables: defined by yourself for custom purposes. User variables can be set inside the launcher (using a "Set variable" action, or a script) and can also be set from external apps such as Tasker or custom components. While builtin variables are currently not read only (you can actually change their value), this is a bad idea to try to set them. Variables types are: boolean, integer, floating point and string. When created, a variable has no value. Usually Lightning Launcher takes care at converting values as needed and you shouldn't have to worry about that. ==== Value ==== The value is used to set the property. Usually values are computed based on variables. A value can be either a single variable, a,short expression including several variables and arithmetic operations, a complex script. A variable is identified by a name staring with "$". Allowed characters in a variable name are a to z, A to Z, 0 to 9 and _ (underscore). If a "$" character need to be included in an expression for something else than a variable name, it must be doubled. See examples below. If the value is made of more than one statement (loop, condition, etc.), it must include a return statement. See examples below. Instances of expressions and values: ^ Expression ^ Result ^ |$cpu_usage | The value of the builtin 'cpu_usage' variable| |4+5|Result is 9| |$screen_width/2 | Center of the screen| |"Current second is: "+$ll_second|Would compute something like "Current second is: 34"| |Math.cos($rotation)|Evaluates the cosinus of the 'rotation' variable| |$ll_hour24+":"+$ll_minute+":"+$ll_second|Would evaluate to the current time, such as "15:47:23"| |var s="";for(var i=0; i<$count; i++) s+="*"; return s|Compose a text made of 'count' times the character "*". Note the use of an explicit "return"| |$battery_level<15 ? "low" : "ok"| Would return "low" if the battery need to be charged, "ok" otherwise| |if($battery_level<15) return "low" else return "ok"| Would return "low" if the battery need to be charged, "ok" otherwise| |"Price in $$US is "+$price|Would compute something like "Price in $US is 3" (escape '$')| ==== Animation ==== Lighting Launcher can take care of smooth transition between the old and the new value of a variable. For instance, let's say an item has a binding associating the variable "alpha" with the property "Transparency". The value for this binding would be "$alpha". Toggling the "alpha" variable between 255 and 0 would suddenly make the item appear and disappear. To make the item smoothly appear and disappear, use the "animate" function (see examples below). The animate function can take up to 4 parameters: - The variable name, including the "$" character (mandatory) - The animation duration in milliseconds. (optional, default is 400ms) - The interpolator name (optional, default is "ad") * li: linear * ac: accelerate * de: decelerate * ad: accelerate / decelerate * an: anticipate * ov: overshoot * bo: bounce - The animation offset in milliseconds. (optional, default is 0ms) **Important note #1:** don't forget the "$" character in front of the variable name. **Important note #2:** all parameters given to 'animate' must be constant values. The behavior will be undefined if arguments are modified during an animation. Also the variable name must be a clear text value. **Important note #3:** keep in mind that animations have a cost and can drain the battery if animations are running all the time. Examples: ^ Expression ^ What it does^ |$alpha|No animation, use the value of the "alpha" variable as is| |animate('$alpha')|Smoothly change the result when changing the value of the "alpha" variable, with the default duration 400ms and the default interpolator "ad"| |animate('$alpha', 2000)|Animate the transparency over 2 seconds| |animate('$alpha', 2000, "li")|Animate the transparency over 2 seconds with a linear interpolator| |animate('$alpha', 2000, "li", 1000)|Animate the transparency over 2 seconds with a linear interpolator and starting one second after the "alpha" variable value change| |animate('$alpha')/2|Animate between 0 and 100 if the "alpha" variable has been changed from 0 to 200| |<del>animate('$alpha/2')</del>|Invalid expression, the first argument must be a variable name only, use the result of animate for further computation| |255*(animate('$ll_second')%1)|Make the item blink every second| ==== Implicit variables ==== When evaluating a binding formula, the following variables are available for use in scripts: * item : the object being processed ([[http://www.pierrox.net/android/applications/lightning_launcher/script/reference/net/pierrox/lightning_launcher/script/api/Item.html|as defined here]]) * field : the internal property name, which list can be found in the [[http://www.pierrox.net/android/applications/lightning_launcher/script/reference/net/pierrox/lightning_launcher/script/api/PropertySet.html|PropertySet]] documentation. ===== Setting variables ===== Variables can be set from several places: from a Lightning Action "Set a variable", from a script or from Tasker. ==== The Lightning Action "Set a variable" ==== This is an easy to use action that can be used as a shortcut or with events such as tap, long tap, swipe, etc. This action is configured with two fields: the variable name (without $), and the value to assign to the variable. Starting at Lightning v12.5b5 the value is evaluated as a JavaScript expression like in bindings, for more flexibility and reduced need of additional scripts when toggling states. If the expression is not a valid JavaScript expression, it is used as is. Sample values with their result: ^ Value ^ Result^ |hello|The text 'hello'| |t+1|The text 't+1'| |$t+1|Assuming the variable 't' has no value yet, the numerical value 1, then 2 if set again, then 3, 4, 5...| |hello+goodbye|The text "hello+goodbye"| |"hello"+"goodbye"|The text "hellogoodbye", notice the difference with the expression above| |1+2|The value '3' (it is evaluated as a JavaScript expression)| |"1+2"|The value '1+2' (enforce textual evaluation)| |abcd"efgh|The text 'abcd"efgh'| |"abcd\"efgh"|The text 'abcd"efgh' (escaped double quote in a JavaScript expression, notice the difference with the example above)| |1-$t|A handy way to toggle between 0 and 1 (if the variable 't' has a numerical value or no value)| |$t==400 ? 100 : 400|Toggle between 100 and 400 (if the variable 't' has a numerical value or no value)| |Math.cos($a)+Math.sin($b)|Computation using several variables and JavaScript math functions| |var s=""; for(var i=0; i<$t; i++) s+"*"; return s;|Build a text made of 't' times the * character. Notice the use of 'return' in a multi statement expression| ==== Setting a variable from script ==== Use one of the LL.setVariable//Type// method to set a single variable, where //Type// is Boolean, Integer, Float or String. When setting several variables at once it is more efficient to group updates this way: <sxh javascript;> var editor = LL.getVariables().edit(); editor.setBoolean("a", true); editor.setInteger("b", 3); editor.setFloat("c", "4.57"); editor.commit(); </sxh> Reference: see [[http://www.pierrox.net/android/applications/lightning_launcher/script/reference/net/pierrox/lightning_launcher/script/api/LL.html||API documentation]] ==== Setting a variable from Tasker ==== Please refer to [[working_with_tasker#setting_variables_inside_lightning_from_a_tasker_task|this link]].
