Keyboard Maestro 6
Conduct your Mac Like a Pro!
Keyboard Maestro 6
Conduct your Mac Like a Pro!
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 trigger a macro by typing a string. Or you can display the containing Macro Group as a floating palette, or execute macros remotely via the built-in web server.
You can also trigger macros by name using the Trigger Macros by Name action, which in turn can be in a macro and triggered any way you desire.
The most common Macro Trigger is the traditional Hot Key. You execute a Macro by pressing 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.
You can type the desired key or key combination in the hot key box, or select a predefined key (holding down any desired modifiers) from the popup menu to its right. Note that there is a relatively prevalent third party / system bug that makes the system think it is permanently in a password filed, and this will prevent entering a hot key by typing in this manner.
The macro can execute when the hot key is pressed, released or repeat 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 to remap command keys (although you can also 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.
To further help with this, if multiple macros are executed with the same hot key, the conflicting macros are displayed in a palette allowing you to select the desired macro. You can select a macro from the palette using either number keys, or by typing the first distinct character to filter the macros down until only one is left. You could use this feature to allow a single hot key to do multiple user-selected actions.
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. Triggers can include non-ASCII characters, but you should verify that the deletes work appropriately in these cases.
WARNING: You should generally not use a Typed String trigger that simulates deletes in a non-text typing context, as the simulated delete keystrokes could be destructive.
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.
Keyboard Maestro will accept the trigger even if you use the delete key to correct it (for example, in the case above, if you typed "=en«delete»m=" the trigger will still fire. If you need to type the trigger text without the macro firing, type and delete a Shift-Space in the middle, like "=e«Shift-Space»«delete»m=".
As above, typing Shift-Space will cancel the sequence, as will any control key or command key (eg Command-.), any macro execution, switching applications, clicking the mouse, or not typing for more than a few seconds.
You can optionally allow typed string triggers to work regardless of case, regardless of diacriticals, or to remember the case of the typed string and mimic the case in any Insert Text actions. You can limit the typed string trigger to only work after a word break (which means any non-alphanumeric character, or any case that cancels the sequence as described above).
Alternatively, you can use a regular expression to match a trigger. The trigger is matched against the end of the typing sequence, so there is an implicit \z on the end of the regular expression. Note that it would be useless to try to match a word break at the end with \b or some sort of positive or negative lookahead assertion as the typing sequence always ends at the current character. So for example "ell\b" would match "hell" even if the next character you planned on typing was an "o".
You can use the %TriggerValue% Text Tokens to determine the exact text that was typed.
If multiple typed string triggers match from the end (eg "hello" and "llo"), the longest will be used. If there are multiple matches with the same length (as can occur if you use the case or diacritic options), the conflict palette will be displayed, offering a selection of the matching macros. In this case, if all of the typed string triggers have the "Simulate N deletes before executing" option enabled, the deletes will be simulated immediately and then the conflict palette will be displayed; otherwise the deletes will not be simulated.
Note that the system will not allow Keyboard Maestro to see keys typed in password fields, so Typed String triggers will not fire if you type them in most password fields. You can use Insert Text by Typing to type in to password fields (although this is a serious security concern), but you cannot use Typed String triggers while inside a password field.
Note also that there is a relatively prevalent third party / system bug that makes the system think it is permanently in a password filed, and thus will prevent typed string triggers from working.
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.
You can use the Login trigger to execute a macro when you login, assuming Keyboard Maestro Engine is launched at login, as it will be if the “Launch Engine at Login” preference in the General preference pane) is checked.
You could use a trigger like this to set up your Mac environment when you start your Mac.
You can use the Engine Launch trigger to execute a macro when the Keyboard Maestro engine launches. Typically, this will be when you login, but it could also be at other times if you quit and restart the engine for any reason, or launch the editor or engine at some time after login.
You can use the System 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.
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.
Keep in mind that the Mac itself must be awake for the macro to run – you can configure a time to wake from sleep in System Preferences. Also, if the screen is screen saving or the display is asleep, UI actions like typing keystrokes or selecting menus will not work. The actions that wake the display and/or stop the screen saver may be useful to resolve some of these issues.
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.
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.
You can control the sorting order of macros by adding two characters and a closing parenthesis (eg “01)My Macro”). The prefix will be removed before displaying in the macro palette, but will be used to control the order of the macros shown.
You can edit a macro by holding down the option key and selecting it from the macro palette.
You can have a macro execute when you select it from the Keyboard Maestro Status Menu (accessed by the Keyboard Maestro icon on the right hand side of the menu bar). You add a macro to the Status Menu by including the Status Menu trigger as a Macro trigger.
Keyboard Maestro will only display the Status Menu triggered macros that are active, so if your Macro is restricted to particular applications, then it will only appear in in the Status Menu while those applications are active.
The Status Menu 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, but will be used to control the order of the macros shown.
You can edit a macro by holding down the option key and selecting it from the status menu.
Keyboard Maestro has an built-in 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 at the time).
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.
Keyboard Maestro can trigger a macro when a volume (disk) is mounted or unmounted.
You could use this trigger to perform actions when you connect a backup disk, or automatically sync files with a disk when it is mounted.
Keyboard Maestro can trigger a macro when a USB Device is attached or detached.
A great use for this trigger is to launch your scanner software when you turn on your scanner, and quit it when you turn off your scanner.
Keyboard Maestro can trigger a macro when you connect or disconnect from a specific wireless network.
Since you typically have a well known specific wireless network at home and at work, you can use this trigger with a MacBook to configure your Mac for work or home use. An obvious use for this is to change your network location when you connect to a wireless network using the Set Network Location action.
Keep in mind that you will disconnect and reconnect your wireless network every time you sleep and wake your Mac. You can get the current Wireless Network Name(s) or Network Location using the appropriate Text Tokens.
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 repeat continuously 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.
Unlike hot key triggers, the pressed key is not removed or affected in any way. 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.
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.
Keyboard Maestro can be triggered from an AppleScript or shell script.
tell application "Keyboard Maestro Engine" do script "[Name or UID of Your Macro]" end tell
or
osascript -e 'tell app "Keyboard Maestro Engine" to do script "[Name or UID of Your Macro]"'
Select from the Or by Script menu to show example code for triggering a macro from Apple Script, shell script, Perl, Python or Ruby.
The macro must be defined and currently active, meaning it must be enabled and the Macro Group that contains it must be enabled and active.