Keyboard Maestro IconKeyboard Maestro

Conduct your Mac Like a Pro!

Macro Triggers

Overview

A Macro is executed when any of its Macro Triggers is activated. There are several triggers to choose from (detailed below), the most common being a Hot key, that is a Macro is executed in response to a keystroke, usually in conjunction with one or more modifier keys. You can also create a floating palette of macros, execute macros in response to applications launching or quitting, execute them remotely via the in-built web server, or at a particular time of day, as well as other possible events.

Hot Key

The most common Macro Trigger is the traditional Hot Key. You execute a Macro by pressing a key combination - a keyboard key like a letter, number, symbol or function key, often in combination with one or more modifiers (shift, control, option and/or command). Almost any key can be a trigger, and keep in mind the number pad counts as different keys to the numeric keys on the main keyboard.

The macro can execute when the hot key is pressed, released or continuously while it is held down. This allows you to do things like have a macro execute when the key is pressed, and then a second macro execute when the key is released, for example to toggle a setting on and then off again.

A common use for Hot Key triggers is to open applications or documents, insert text templates, or as a way of remapping command keys (although you can remap command keys in the System Preferences Keyboard preference settings).

Hot Keys suffer from the drawback that you need to remember a cryptic keystroke. This can be mitigated by selecting consistent keystrokes (such as control-letter to mean insert text and control-option-letter to mean launch an application). You can also use a tool like KeyCue to display command keys and macro hot keys.

If multiple macros are executed with the same hot key, the duplicate macros are displayed in a palette allowing you to select the desired macro. You could use this feature to allow a single hot key to do multiple user-selected actions. Pressing a number key will allow you to execute a macro without using the mouse, or press escape or take any other action to cancel.

Typed String

The Typed String trigger lets you execute a macro in response to a sequence of keys.

Typed String triggers allow you to use more verbose (and hence descriptive) sequences of keys to trigger a macro. Because the keys first go through to the current application, the keys are usually deleted prior to executing the macro, although with this disabled you can use it in an application that largely ignores keys. For this reason, the allowed keys in a Typed String macro are limited to plain 7-bit ASCII characters.

To avoid macros firing unexpectedly it is a good idea to include a consistent prefix and/or suffix to your strings. For example, to insert your email address, rather than use just “em” (which would fire if you typed “them”, use something like “=em=” which you will not type accidentally.

Application

You can have a Macro execute in response to an application event, such as when the specified application launches, quits, activates or deactivates. You can also have the Macro run periodically while an application is running or while it is at the front.

You could use a trigger like this to simulate workspaces by automatically setting up an application the way you want when you launch it, or you could clean up after an application when you quit.

As with all triggers, the trigger will fire only if the Macro Group that contains it is active, which is based on the current foreground application before the specified application launches, or after the specified application is deactivated or quits. In practice, this means the Macro Groups that contain this trigger should be targeted at All Applications.

Wake

You can use the Wake trigger to execute a macro when your Mac wakes from sleep.

You could use a trigger like this to set up your Mac environment, first determining your location and then taking appropriate action.

Login

You can use the Login trigger to execute a macro when you login.

You could use a trigger like this to set up your Mac environment when you start your Mac.

Time

You can use the Time trigger to execute a macro at a specific time, optionally restricted to certain days of the week.

You could use a trigger like this to set up your Mac environment before arriving at work, run periodic maintenance or backup scripts late on the weekend, or launch iChat for your weekly video conference.

While Logged In

You can use the While Logged In trigger to repeatedly execute a macro during a portion of the day, optionally restricted to certain days of the week.

You could use a trigger like this to run periodic maintenance or track changes.

Macro Palette

You can have a macro execute when you click on it in a floating Macro Palette. Keyboard Maestro will only display the palette when there are active Macros, so if your Macros are restricted to particular applications, then the Macro Palette will only appear in those applications. This is particularly useful for less frequently used macros whose Hot Key you might forget, or for complex apps like Final Cut Pro that has so many different but frequently used keyboard shortcuts that you cannot memorize them all.

You could use a trigger like this to add an action palette to an application that does not have such a facility.

You can control the sorting order of macros by adding two characters and a closing braket (eg “01)My Macro”). The prefix will be removed before displaying in the macro palette.

You can edit a macro by holding down the option key and selecting it from the macro palette.

Status Menu

You can have a macro execute when you select it from the Keyboard Maestro Status Menu (on the right hand side of the menu bar). Keyboard Maestro will only display the Status Menu triggered macros that are active, so if your Macros are restricted to particular applications, then they will only appear in those applications. This is particularly useful for less frequently used macros whose Hot Key you might forget.

You could use a trigger like this to add custom facilities to applications, such as to open specific common files or set up windows in specific ways.

You can control the sorting order of macro groups and macros by adding two characters and a closing braket (eg “01)My Macro”). The prefix will be removed before displaying in the status menu.

You can edit a macro by holding down the option key and selecting it from the status menu.

Public Web

Keyboard Maestro has an in-built web server. You can enable it in the Web Server preference pane. If enabled, and if you configure a username and password, you can connect to your Keyboard Maestro’s web server and login and then execute any macro you have defined. Also, if the web server is enabled, and if you have configured any Macro with a Public Web trigger, then anyone on the Internet can connect to your Mac and trigger Public Web macros.

Macros are only available if they are currently active (ie, they must not be disabled or in a Macro Group that is disabled, and their Macro Group must be currently active which depends on the current application).

For example, if you are running some sort of process on your Mac that occasionally fails, you could write a script to restart it and make it available as a Public Web triggered Macro, which you (or anyone else) could then execute to restart the process.

Clearly there are some serious security issues with this, so you should use a lot of caution when you allow any macro to be executed with a Public Web trigger.

Device Key

This is an advanced trigger—generally you should use a Hot Key Trigger if possible.

Keyboard Maestro can trigger a macro when any device key is pressed—this includes modifier keys, mouse buttons, programable keyboards like P.I. Engineering’s X-Key, and even the brightness buttons on USB connected monitors.

The macro can be executed when the key is pressed, released or periodically while it is held down. The trigger can also optionally be restricted to when certain modifier keys are pressed.

For example, a macro could fire every five seconds while control-Mouse Button 3 is held down.

This trigger watches input devices at a low level, but it does not affect them, so any key presses continue to have their normal operation as well as triggering the macro. This is fine for modifiers, unused mouse buttons, programable keyboards and other unused buttons, but would likely be problematic for normal keystrokes which will continue to have some other probably unwanted affect.

MIDI Note

Keyboard Maestro can trigger a macro when it recieves a MIDI note. You execute a Macro by pressing a key on a MIDI device like an electronic Keyboard.

The macro can execute when the MIDI note is pressed (note on), released (note off) or continuously while it is held down. This allows you to do things like have a macro execute when the key is pressed, and then a second macro execute when the key is released, for example to toggle a setting on and then off again.

Continue on to Recording

Close

Feedback Form

Please provide any feedback you may have


Email Address:
Subject:
Feedback:


Your email address is appreciated but is not required and will not be saved.
It will be used only for responding to or clarifying this feedback.

Documentation

Old Documentation