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 [2018/05/16 23:21]
JMichaelTX
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 23: Line 23:
 Operators based on precedence from lowest to highest are: Operators based on precedence from lowest to highest are:
  
-| Array Separator (`,`)\\ FIXME -- this is NOT an //​operator//​ IMO. | Allows a text Variable, which has comma separated values, to work somewhat like an Array.\\ Assume `MyKMVariable` contains "value1,value2,value3".\\ Then `MyKMVariable[2]` returns "value2". |+| 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
-| Arithmetic Operators\\   • Add (`+`)\\   • Subtract (`-`)\\   • Multiply (`*`)\\   • Divide (`/`) | mathematical ​function that takes two operands and performs a calculation on them. | +| Arithmetic ​Addition ​Operators \\   • Add (`+`)\\   • Subtract (`-`) | Basic mathematical operations. | 
-| [Modulo](https://​en.wikipedia.org/​wiki/​Modulo_operation) (`i MOD n`) | The remainder of the division of `i by n`.\\ Both values (`i, n`) must be an integer ​in Keyboard Maestro.  | +| 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 `iby `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 (`√`, `-`, `( )` ) | 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\\ FIXME -- While technically ​Functions ​are operators, it confusing to most users to list here since everywhere else in KM they are separated. ​| a large variety of functions | +| Power Operator (`^`) | exponentiation
-| Numbers and Variables or Array Accesses (5,​$5A,​0x50,​8#​007,​Variable,​Variable[5])\\ FIXME -- this is clear as mud. | identifiers and values | +| Unary Prefix Operators (`√`, `-`, `( )` ) | square root, negation, sub-expressions
-| Unary Postfix Operators (`!,%,°`)) | 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|
  
-You can use either `=` or `==` (v8+) for testing for equality.+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.
Line 44: Line 50:
 The available functions are listed on the [[/​Functions|wiki Functions page]]. The available functions are listed on the [[/​Functions|wiki Functions page]].
  
-You can insert a function by name by choosing [[Menus#Insert_Function_by_Name|Insert Function ​by Name]] from the [[Menus#Edit|Edit menu]].+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 ===== ===== 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 ​(v8+) 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. +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.
- +
-===== Screen Coordinates ===== +
- +
-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 Array Access ===== ===== Variable Array Access =====
Line 71: Line 64:
 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`). 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`).
  
-===== Variable ​Dot Notation =====+===== 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). 
 + 
 +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 86: 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.
 +
 ===== Text Fields ===== ===== Text Fields =====
  
Line 96: Line 101:
 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]]. 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%.+    The result is %Calculate% 3 * Count + 7 %.
  
-===== Examples of Variable ​Data Reference =====+===== Examples of Variable ​Array Reference =====
  
-** Macro Actions**\\ +=== Macro Actions ​===
-{{:​manual:​window-frame-example-actions-km-7.3.png?​nolink|}}+
  
-**Example Results**\\ +{{ window-frame-example-actions.png?nolink&​584x592 ​Window Frame Example Actions ​}}
-{{:manual:window-frame-example-results-km-7.3.png?​nolink|}}+
  
-Some example ​expressions might be:+=== Example Results === 
 + 
 +{{ window-frame-example-results.png?​nolink&​487x495 | Window Frame Example Results }} 
 + 
 +===== 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 119: Line 126:
 </​code>​ </​code>​
  
---- 
- 
-**KeyWords:​** ​ MOD, Modulo 
manual/Calculations.1526527295.txt.gz · Last modified: 2018/05/16 23:21 by JMichaelTX