Calculations

Keyboard Maestro supports calculations in almost any numeric field. 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, for example:

Set variable ‘Temp’ To Text ‘%FrontWindowFrame%’
Set variable ‘Temp’ To Calculation ‘Temp[1]+Temp[3]/2,Temp[2]+Temp[4]/2’
Use ‘Temp’ to Set the Mouse Location

will result in the mouse being placed at the center of the front window.

Unfortunately, because of this you must use commas for this purpose, and full stops (.) for decimal numbers, regardless of your desired language, and never use any thousands separators.

Keyboard Maestro’s expressions include precedence, nested bracketed expressions, many built-in functions, various numeric bases, so you should be able to write most expressions you might like to use, as well as use it as a general purpose calculator if desired.

Operators based on precedence from lowest to highest are:

array separator (,)

separates elements of an array.

ternary operator (?)

a=b ? 3 : 4.

bitwise or (|), bitwise and (&) and bitwise xor

operators.

comparison operators (<, ≤, =, >, ≥, ≠)

compare for (in)equality and return 0 or 1.

shift operators (≪, ≫)

shift a number left or right.

addition operators (+, -)

add or subtract.

multiplication operators (*, /, MOD)

multiply, divide or mod.

power operator (^)

exponentiation.

unary prefix operators (√, -, brackets)

square root, negation, sub-expressions.

functions

a 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.

To minimize conflict with variables, operators and functions must be in uppercase.

Supported functions include:

SIN, COS, TAN, ASIN, ACOS, ATAN, ATAN2

trigonometry functions

SINH, COSH, TANH, ASINH, ACOSH, ATANH

hyperbolic trigonometry functions

EXP

exponentiation of e.

LOG or LN

logarithm base e.

LOG2, LOG10

logarithm base 2 or 10.

ABS

absolute value.

CEIL, FLOOR

integer ceiling or floor.

TRUNC, ROUND

truncate or round.

MIN, MAX

Minimum or maximum.

RANDOM

random real number from 0 to, but not including, N (defaults to 1).

RAND

random integer number from 0 to, but not including, N.

MICROSECONDS or MICROS

microseconds since startup.

MILLISECONDS or MILLS or MS

fractional milliseconds since startup.

SECONDS

fractional seconds since startup.

NOW

current time in seconds since the start of 1970.

TRIGGERTIME

the time in (fractional) seconds since the start of 1970 when the macro was triggered.

IDLE

the number of (fractional) seconds the Mac has been idle.

TIME

current time in seconds since the start of 1970.

JULIANDATE or JD

days (and fractions of days) since January 1, 4713 BC Greenwich noon.

MJD

days since the start of November 17, 1858.

TIME2JD

convert time from unix TIME to JULIANDATE.

TIME2MJD

convert time from unix TIME to MJD.

JD2MJD

convert time from JULIANDATE to MJD.

JD2TIME

convert time from JULIANDATE to TIME.

MJD2TIME

convert time from MJD to TIME.

MJD2JD

convert time from MJD to JULIANDATE.

YEAR

get the year component from a unix time (seconds since the start of 1970).

MONTH

get the month component from a unix time.

DAY

get the day component from a unix time.

DOW

get the day of the week (1 = Sunday, 7=Saturday) component from a unix time.

HOUR

get the hour component from a unix time.

MINUTE

get the minute component from a unix time.

SECOND

get the second component from a unix time.

GMTOFFSET

get the number of seconds from GMT.

MOUSEX

the x coordinate of the current mouse location.

MOUSEY

the y coordinate of the current mouse location.

MOUSEBUTTON

1 if the corresponding button is pressed, 0 otherwise.

SCREEN( n, Left|Right|Top|Bottom|Width|Height|MidX|MidY, p )

screen frame coordinates.

WINDOW( n, Left|Right|Top|Bottom|Width|Height|MidX|MidY )

window frame coordinates.

SCREENCOUNT

the number of screens (displays).

WINDOWCOUNT

the number of windows in the front application.

APPLICATIONS

the number of running applications.

SAFARITABCOUNT

the number oftabs in the front Safari window.

SAFARITABINDEX

the index of the selected tab in the front Safari window.

SAFARIISCOMPLETE

whether Safari has currenlty finished loading the current tab.

CHROMETABCOUNT

the number oftabs in the front Google Chrome window.

CHROMETABINDEX

the index of the selected tab in the front Google Chrome window.

CHROMEISCOMPLETE

whether Google Chrome has currenlty finished loading the current tab.

MAILDATERECEIVED

the date received of the currently selected mail message.

MAILDATESENT

the date sent of the currently selected mail message.

MAILFLAG

the flag of the currently selected mail message.

MAILFLAGGED

the flagged status of the currently selected mail message.

MAILREADSTATUS

the read status of the currently selected mail message.

MAILJUNKSTATUS

the junk status of the currently selected mail message.

MAILWASFORWARDED

the was forwarded status of the currently selected mail message.

MAILWASREDIRECTED

the was redirected status of the currently selected mail message.

MAILWASREPLIEDTO

the was replied to status of the currently selected mail message.

ONLINE

whether the Mac is currently connected to the Internet.

BATTERY

whether the Mac is currently running off battery power.

SCREENSAVER

whether the Mac is currently displaying the screen saver (or the display is off).

SYSTEMVOLUME

current system sound output volume (0-100).

CLIPBOARDSEED

an integer that changes when the clipboard changes.

The JD, MJD, and TIME functions return the current date and time, or can take the date (year, month, day) or date and time (year, month, day, hour, minute, seconds) to return.

The YEAR, MONTH, DAY, DOW, HOUR, MINUTE, SECOND functions return the relevant component of the current time or the can take the a unix time (seconds since the start of 1970).

The SCREEN index can be 0 for the main screen, and then 1 through n are the screens in orientation order from left to right. The index can also be one of:

Main

the screen with the menu bar.

Second

the left most screen that does not have the menu bar.

Third

the left most screen that is not the Main or Second screen.

Internal

the left most screen that is an internal screen (typically on a laptop).

External

the left most screen that is not an internal screen.

Mouse

the left most screen containing the mouse.

Front

the left most screen containing (the most of) the front window.

Back

the left most screen not containing (the most of) the front window.

Back2

the second left most screen not containing (the most of) the front window.

The optional p parameter specifies a percentage of the width or height to offset by. Eg SCREEN(Internal,Left,10%) would be the coordinate of left edge of the internal screen plus 10% of the width of the internal screen. Offsets are always to the right and down, but negative offsets are allowed.

The WINDOW index can be 0 for the main focussed window, and 1 through n are the screens in Z-order (1 is usually the main window), or -1 through -n in reverse order.

IDLE time is based on the Human Interface (HID) system, and so notices only HID device activity like mouse movement or keyboard presses, not things like disk access or movies playing.

Some actions have one or two images, or refer to a window or some text, and calculations in those actions can include reference to some context sensitive functions:

IMAGE(Width|Height)

the action image size.

SOURCEIMAGE(Width|Height)

the action source image size.

WINDOW(Left|Right|Top|Bottom|Width|Height|MidX|MidY)

the action window coordinates.

LENGTH()

the action text length.

FONTSIZE()

the original font size during the Apply Style action.

Keyboard Maestro refers to points as strings with two values, like 12,34 and to rectangles as four values 12,34,56,78. You can reference these values are arrays (eg Variable[2] would be 34 in either case), but for clarity, you can reference these values using dot notation:

Variable.x

x coordinate.

Variable.y

x coordinate.

Variable.left

the left coordinate of a rectangle.

Variable.top

the top coordinate of a rectangle.

Variable.right

the right coordinate of a rectangle.

Variable.bottom

the right coordinate of a rectangle.

Variable.width

the width of a rectangle.

Variable.height

the height of a rectangle.

Variable.MidX

the horizontal middle of a rectangle.

Variable.MidY

the vertical middle of a rectangle.

Some example functions might be:

 Amount in Dollars * 100
 MJD() > 55928
 NOW() > TIME(2012,3,23,12,2,1)
 DOW(TIME(2012,4,4)) = 4
 Radius*SIN(20°),Radius*COS(20°)
 Window Frame[1]+Window Frame[3]/2,Window Frame[2]+Window Frame[4]/2
 MOUSEBUTTON() + 2 * MOUSEBUTTON(4)
 SCREEN(Internal,Left,10%)

Continue on to Conditions