User Tools

Site Tools


manual:Calculations

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
manual:Calculations [2017/08/24 06:54]
peternlewis [Variable Dot Notation]
manual:Calculations [2023/10/02 00:38] (current)
peternlewis
Line 3: Line 3:
 ===== Overview ===== ===== Overview =====
  
-Keyboard Maestro supports calculations in almost any numeric [[/​Text_Fields|text fields]]. ​ For example you can Pause for "​60*Time in Minutes"​. ​ Calculations can also use comma separated lists of numbers as arrays, and can return such arrays, so you can operate on frames and points. ​ Numeric fields often start small with up/down step arrows, but if you type anything other than a number they will expand to allow a more complex expression to be entered. ​ You can tell that a field accepts calculations because a small BUTTON{{{C}}} shows in the field while editing it.+Keyboard Maestro supports calculations in almost any numeric [[/​Text_Fields|text fields]]. ​ For example you can Pause for "​60*Time in Minutes"​. ​ Calculations can also use comma separated lists of numbers as arrays, and can return such arrays, so you can operate on rectangle ​frames and points. ​ Numeric fields often start small with up/down step arrows, but if you type anything other than a number they will expand to allow a more complex expression to be entered. ​ You can tell that a field accepts calculations because a small BUTTON{{{C}}} shows in the field while editing it. 
 ===== Examples ===== ===== Examples =====
  
Line 22: Line 23:
 Operators based on precedence from lowest to highest are: Operators based on precedence from lowest to highest are:
  
-array separator ​(,) | separates elements of an array +Array Separator ​(`,`) | Allows a text Variable, which has comma separated values, to work somewhat like an Array.\\ Assume `MyKMVariable` contains "​12,​34,​56",​ then `MyKMVariable[2]` returns "​34"​. ​
-ternary operator ​(?) | a=b ? 3 : 4 | +Ternary Operator ​(`?`) | a=b ? 3 : 4 | 
-bitwise or (%%|%%), bitwise and (%%&%%) and bitwise xor | operators | +Bitwise OR (`|`), Bitwise AND (`&`) and Bitwise XOR bitwise ​operators, which also act as logical boolean operators for 0 (false) and 1 (true). ​
-comparison operators ​(<, ≤, =, >, ≥, ≠) | compare for (in)equality and return 0 or 1 | +Comparison Operators ​(`<, ≤, =, >, ≥, ≠`) | compare for (in)equality and return 0 or 1
-shift operators ​(≪, ≫) | shift a number left or right | +Shift Operators ​(`≪, ≫`) | shift a number left or right
-addition operators ​(+-) | add or subtract ​+Arithmetic Addition Operators \\   • Add (`+`)\\   • Subtract (`-`) | Basic mathematical operations. ​
-multiplication operators ​(*/, MOD) | multiply, divide or [Modulo](https://​en.wikipedia.org/​wiki/​Modulo_operation) | +Arithmetic Multiplication Operators \\   • Multiply ​(`*`)\\   • Divide (`/`) | Basic mathematical operations. | 
-power operator ​(%%^%%) | exponentiation | +[Modulo](https://​en.wikipedia.org/​wiki/​Modulo_operation) ​(`i MOD n`) | The remainder of the division of `i` by `n`.\\ Both values (`i`, `n`) will be treated as integer.\\ `n` must not be 0.\\ The sign of the result is the same as the sign of i.  ​
-unary prefix operators ​(√ (Option-V), -, brackets) | square root, negation, sub-expressions | +Integer division ​(`i DIV n`) | The integer quotient of the division of `i` by `n`.\\ Both values (`i`, `n`) will be treated as integer.\\ `n` must not be 0.\\ The sign of the result matches the sign of regular division. ​ | 
-functions ​| a large variety of functions | +| Power Operator (`^`) | exponentiation
-numbers ​and variables ​or array accesses ​(5,​$5A,​0x50,​8#​007,​Variable,​Variable[5]) | identifiers and values | +Unary Prefix Operators ​(```-``( )` ) | square root, negation, sub-expressions
-unary postfix operators ​(!,​%,​° ​(Option-Shift-8)) | factorial, percent, degrees |+[[:​Functions|Functions]] ​| a large variety of functions
 +Numbers ​and Variables ​or Array Accesses ​(5,​$5A,​0x50,​8#​007,​Variable,​Variable[5]) | identifiers and values
 +Unary Postfix Operators ​(`!,%,°`)) | factorial, percent, degrees| 
 + 
 +Numbers are in decimal by default, but may use base 16 if they start with `$` or `0x` (eg $5A or 0x5A), or may start with a specific base followed by a `#` (eg 8#007). Numbers may include underscores,​ for example 1_000_000 or 0xABCD_EF89. 
 + 
 +[[Variables|Variables]] can be used if they contain numeric expressions,​ including an *array* of numbers separated by commas, in which case you can use an array index to select the desired number.  
 + 
 +You can use either `=` or `==` for testing for equality.
  
 Operators and functions must be in uppercase to minimize conflict with variables. Operators and functions must be in uppercase to minimize conflict with variables.
 +
 ===== Functions ===== ===== Functions =====
  
 The available functions are listed on the [[/​Functions|wiki Functions page]]. The available functions are listed on the [[/​Functions|wiki Functions page]].
  
-===== Screen Coordinates =====+You can insert a function by name by choosing from the [[Menus#​Insert_Function|Edit ➤ Insert Function menu]] or choosing the [[Menus#​Insert_Function_by_Name|Edit ➤ Insert Function by Name menu]]. 
 + 
 +===== Variables ===== 
 + 
 +In numeric calculation fields, Variable Names are used without the `%` that are used in text token fields. ​ Do not try to use tokens (like `%Variable%MyVar%`) in numeric calculation fields, just use MyVar by itself. The variable must contain a valid numeric value, or an expression that evaluates to a valid numeric value. ​ So for example, if MyVar contains a text value of `2*3`, then the calculation `4*MyVar` will return 24. 
 + 
 +===== Variable Array Access ===== 
 + 
 +If a variable contains a sequence of numbers separated by comma (,) then you can access that variable using array notation (eg `MyVar[5]`). ​ So if variable MyVar has a text value of `10,​20,​30,​40,​50,​60`,​ MyVar[5] will return 50. 
 + 
 +The index is itself an expression, so it can be arbitrarily complex. 
 + 
 +Indices are 1-based, so MyVar[1] is the first element. ​ If the index is 0, the size of the array is returned (so MyVar[0] would be `6`).  If the index is less than zero, the array is indexed from the end (so MyVar[-5] would be `20`). 
 + 
 +===== Screen Coordinates ​and Dot Notation ​=====
  
 Keyboard Maestro refers to screen coordinates as two or four comma separated numbers in the text of a Keyboard Maestro Variable (which is always a string). Keyboard Maestro refers to screen coordinates as two or four comma separated numbers in the text of a Keyboard Maestro Variable (which is always a string).
-  * Screen object points, like the left,top position of a window, have two values, like 12,34 
-  * Screen object rectangles, like the frame of a window, have four values 12,34,56,78 (with a fifth value for fuzz in some instances).  ​ 
-  * You can reference these values by position in the string, as it the Variable were an array: 
-  * For example:  ​ 
-if the Variable `myWindow` is "​12,​34,​56,​78"  ​ 
-then all of these forms of reference will provide a value of 34 in a Calculation field: 
-    * myWindow[2] 
-    * myWindow.y 
-    * myWindow.Top 
  
-==== Variable Dot Notation ====+Screen object points, like the left,top position of a window, have two values, like 12,34. 
 + 
 +Screen object rectangles, like the frame of a window, have four values 12,34,56,78 (with a fifth value for fuzz in some instances).
  
 In a Calculation field you can reference the numbers in a Keyboard Maestro Variable (which is always a string) using dot notation: In a Calculation field you can reference the numbers in a Keyboard Maestro Variable (which is always a string) using dot notation:
Line 68: Line 85:
 | Variable.MidX | the horizontal middle of a rectangle | | Variable.MidX | the horizontal middle of a rectangle |
 | Variable.MidY | the vertical middle of a rectangle | | Variable.MidY | the vertical middle of a rectangle |
 +
 +For example if the Variable `myWindow` is "​12,​34,​56,​78"​ then all of these forms of reference will provide a value of 34 in a Calculation field:
 +    * myWindow[2]
 +    * myWindow.y
 +    * myWindow.Top
  
 The Variable Name and Dot reference are case insensitive. The Variable Name and Dot reference are case insensitive.
  
-==== Examples of Variable ​Data Reference ====+===== Text Fields ===== 
 + 
 +In calculation fields, you can express a calculation as you would normally write an expression, for example: 
 + 
 +    3 * Count + 7 
 + 
 +However in a text field, since any text is allowed, you must use percent encoded tokens to indicate where more processing is required. ​ You can include a variable in the text by using the [[token:​Variable|%Variable%]] token, or you can use a calculation by using the [[token:​Calculate|%Calculate%]] token, or any number of other [[:​Tokens|Tokens]]. 
 + 
 +    The result is %Calculate% 3 * Count + 7 %. 
 + 
 +===== Examples of Variable ​Array Reference ====
 + 
 +=== Macro Actions === 
 + 
 +{{ window-frame-example-actions.png?​nolink&​584x592 | Window Frame Example Actions }}
  
-** Macro Actions**\\ +=== Example Results ===
-{{:​manual:​window-frame-example-actions-km-7.3.png?​nolink|}}+
  
-**Example Results**\\ +{{ window-frame-example-results.png?​nolink&​487x495 ​Window Frame Example Results ​}}
-{{:manual:window-frame-example-results-km-7.3.png?​nolink|}}+
  
-Some example expressions might be:+===== Example Expressions =====
  
 <​code>​ <​code>​
 Amount in Dollars * 100 Amount in Dollars * 100
 MJD() > 55928 MJD() > 55928
-NOW() > TIME(2012,​3,​23,​12,​2,​1) +NOW() > TIME(2023,​3,​23,​12,​2,​1) 
-DOW(TIME(2012,4,4)) = 4+DOW(TIME(2023,4,4)) = 4
 Radius*SIN(20°),​Radius*COS(20°) Radius*SIN(20°),​Radius*COS(20°)
 Window Frame[1]+Window Frame[3]/​2,​Window Frame.MidY Window Frame[1]+Window Frame[3]/​2,​Window Frame.MidY
Line 91: Line 125:
 SCREEN(Internal,​Left,​10%) SCREEN(Internal,​Left,​10%)
 </​code>​ </​code>​
- 
  
manual/Calculations.1503572085.txt.gz · Last modified: 2017/08/24 06:54 by peternlewis