Key Press actions

In a Key Press action, PopClip will simulate a key press, or sequence of presses, as if it was performed by the user.

Pressing a key from JavaScript

You can also use popclip.pressKey() — or popclip.pressKeys(), for a sequence of combos with optional waits — within a JavaScript action.

Properties

A Key Press action is defined by the presence of a keyCombo or keyCombos field, as follows:

Key	Type	Description
keyCombo	String	The key combination to press, as defined in String format.
keyCombos	Array	Instead of a single key combo, you can supply array of them. PopClip will press all the key combos in sequence.
keyComboTarget	String	Where to post the presses: session (the default), app or hid. See Target.

Target

The keyComboTarget field says where PopClip posts the key events:

Value	Description
session	To the session event tap, kCGSessionEventTap. This is the default.
app	To the process of the application the action is acting on, using CGEventPostToPid().
hid	To the HID event tap, kCGHIDEventTap.

Use the app target if the key combination is intended only for the target app — an example would be a formatting extension that presses ⌘B, ⌘I and ⌘U. Keep the default session if the key combination is intended to activate a global shortcut. Posting to hid is not normally needed, but it may work in some cases where posting to session fails.

#popclip
name: Bold
keyCombo: command b
keyComboTarget: app
stayVisible: true

Input and output

Key Press actions do not receive any input or return any output.

String format

The string format is a convenient human-readable format that can specify a key and modifiers. For example:

• command b or command B- Hold command, and press 'b' key
• option shift . - Hold option and shift, and press the dot key
• command space - Hold command, and press space bar
• f1 - The F1 key on its own with no modifiers
• option numpad / - Hold option, press '/' key on numeric keypad
• 0x74 - 0x74 is the hex numeric code for the Page Up key

The format is: <modifiers> <key>, where:

• <modifiers> is optional, and can be any combination of:

Modifier	Keyword
Command (⌘)	command, cmd
Option (⌥)	option, opt
Control (⌃)	control, ctrl
Shift (⇧)	shift
Numeric Keypad	numpad

• <key> is the key to press, either:
  • A character, as printed on the key. Not case-sensitive. Examples: A, a, ;, 9.
  • A key name. The following are supported: return, space, delete, escape, left, right, down, up, and f1 ... f20.
  • A hexadecimal key code, starting with 0x. See list of codes below.

List of virtual key codes (from Apple's Events.h)

/*
 *  Summary:
 *    Virtual keycodes
 *
 *  Discussion:
 *    These constants are the virtual keycodes defined originally in
 *    Inside Mac Volume V, pg. V-191. They identify physical keys on a
 *    keyboard. Those constants with "ANSI" in the name are labeled
 *    according to the key position on an ANSI-standard US keyboard.
 *    For example, kVK_ANSI_A indicates the virtual keycode for the key
 *    with the letter 'A' in the US keyboard layout. Other keyboard
 *    layouts may have the 'A' key label on a different physical key;
 *    in this case, pressing 'A' will generate a different virtual
 *    keycode.
 */
enum {
  kVK_ANSI_A                    = 0x00,
  kVK_ANSI_S                    = 0x01,
  kVK_ANSI_D                    = 0x02,
  kVK_ANSI_F                    = 0x03,
  kVK_ANSI_H                    = 0x04,
  kVK_ANSI_G                    = 0x05,
  kVK_ANSI_Z                    = 0x06,
  kVK_ANSI_X                    = 0x07,
  kVK_ANSI_C                    = 0x08,
  kVK_ANSI_V                    = 0x09,
  kVK_ANSI_B                    = 0x0B,
  kVK_ANSI_Q                    = 0x0C,
  kVK_ANSI_W                    = 0x0D,
  kVK_ANSI_E                    = 0x0E,
  kVK_ANSI_R                    = 0x0F,
  kVK_ANSI_Y                    = 0x10,
  kVK_ANSI_T                    = 0x11,
  kVK_ANSI_1                    = 0x12,
  kVK_ANSI_2                    = 0x13,
  kVK_ANSI_3                    = 0x14,
  kVK_ANSI_4                    = 0x15,
  kVK_ANSI_6                    = 0x16,
  kVK_ANSI_5                    = 0x17,
  kVK_ANSI_Equal                = 0x18,
  kVK_ANSI_9                    = 0x19,
  kVK_ANSI_7                    = 0x1A,
  kVK_ANSI_Minus                = 0x1B,
  kVK_ANSI_8                    = 0x1C,
  kVK_ANSI_0                    = 0x1D,
  kVK_ANSI_RightBracket         = 0x1E,
  kVK_ANSI_O                    = 0x1F,
  kVK_ANSI_U                    = 0x20,
  kVK_ANSI_LeftBracket          = 0x21,
  kVK_ANSI_I                    = 0x22,
  kVK_ANSI_P                    = 0x23,
  kVK_ANSI_L                    = 0x25,
  kVK_ANSI_J                    = 0x26,
  kVK_ANSI_Quote                = 0x27,
  kVK_ANSI_K                    = 0x28,
  kVK_ANSI_Semicolon            = 0x29,
  kVK_ANSI_Backslash            = 0x2A,
  kVK_ANSI_Comma                = 0x2B,
  kVK_ANSI_Slash                = 0x2C,
  kVK_ANSI_N                    = 0x2D,
  kVK_ANSI_M                    = 0x2E,
  kVK_ANSI_Period               = 0x2F,
  kVK_ANSI_Grave                = 0x32,
  kVK_ANSI_KeypadDecimal        = 0x41,
  kVK_ANSI_KeypadMultiply       = 0x43,
  kVK_ANSI_KeypadPlus           = 0x45,
  kVK_ANSI_KeypadClear          = 0x47,
  kVK_ANSI_KeypadDivide         = 0x4B,
  kVK_ANSI_KeypadEnter          = 0x4C,
  kVK_ANSI_KeypadMinus          = 0x4E,
  kVK_ANSI_KeypadEquals         = 0x51,
  kVK_ANSI_Keypad0              = 0x52,
  kVK_ANSI_Keypad1              = 0x53,
  kVK_ANSI_Keypad2              = 0x54,
  kVK_ANSI_Keypad3              = 0x55,
  kVK_ANSI_Keypad4              = 0x56,
  kVK_ANSI_Keypad5              = 0x57,
  kVK_ANSI_Keypad6              = 0x58,
  kVK_ANSI_Keypad7              = 0x59,
  kVK_ANSI_Keypad8              = 0x5B,
  kVK_ANSI_Keypad9              = 0x5C
};

/* keycodes for keys that are independent of keyboard layout*/
enum {
  kVK_Return                    = 0x24,
  kVK_Tab                       = 0x30,
  kVK_Space                     = 0x31,
  kVK_Delete                    = 0x33,
  kVK_Escape                    = 0x35,
  kVK_Command                   = 0x37,
  kVK_Shift                     = 0x38,
  kVK_CapsLock                  = 0x39,
  kVK_Option                    = 0x3A,
  kVK_Control                   = 0x3B,
  kVK_RightCommand              = 0x36,
  kVK_RightShift                = 0x3C,
  kVK_RightOption               = 0x3D,
  kVK_RightControl              = 0x3E,
  kVK_Function                  = 0x3F,
  kVK_F17                       = 0x40,
  kVK_VolumeUp                  = 0x48,
  kVK_VolumeDown                = 0x49,
  kVK_Mute                      = 0x4A,
  kVK_F18                       = 0x4F,
  kVK_F19                       = 0x50,
  kVK_F20                       = 0x5A,
  kVK_F5                        = 0x60,
  kVK_F6                        = 0x61,
  kVK_F7                        = 0x62,
  kVK_F3                        = 0x63,
  kVK_F8                        = 0x64,
  kVK_F9                        = 0x65,
  kVK_F11                       = 0x67,
  kVK_F13                       = 0x69,
  kVK_F16                       = 0x6A,
  kVK_F14                       = 0x6B,
  kVK_F10                       = 0x6D,
  kVK_F12                       = 0x6F,
  kVK_F15                       = 0x71,
  kVK_Help                      = 0x72,
  kVK_Home                      = 0x73,
  kVK_PageUp                    = 0x74,
  kVK_ForwardDelete             = 0x75,
  kVK_F4                        = 0x76,
  kVK_End                       = 0x77,
  kVK_F2                        = 0x78,
  kVK_PageDown                  = 0x79,
  kVK_F1                        = 0x7A,
  kVK_LeftArrow                 = 0x7B,
  kVK_RightArrow                = 0x7C,
  kVK_DownArrow                 = 0x7D,
  kVK_UpArrow                   = 0x7E
};

/* ISO keyboards only*/
enum {
  kVK_ISO_Section               = 0x0A
};

/* JIS keyboards only*/
enum {
  kVK_JIS_Yen                   = 0x5D,
  kVK_JIS_Underscore            = 0x5E,
  kVK_JIS_KeypadComma           = 0x5F,
  kVK_JIS_Eisu                  = 0x66,
  kVK_JIS_Kana                  = 0x68
};

Wait between key presses

By default, PopClip does not wait between key presses. To add a delay, put wait <milliseconds> in the keyCombos array. For example, wait 100 will wait 100 milliseconds. (See example below.)

Examples

A simple key press to make text bold in most editors:

#popclip
name: Bold
icon: B
keyCombo: command b

Pressing a sequence of keys:

#popclip
name: Paste and Enter
icon: square monospaced ↵
requirements: [paste] # only show action when there is something to paste
keyCombos:
  - command v
  - return

Pressing a sequence of keys, with a wait included:

#popclip
name: Spotlight
before: copy # puts selected text on the clipboard
keyCombos:
  - command space
  - wait 50 # waits 50 milliseconds
  - command v

A "Superscript" extension, supporting a couple of different apps:

#popclip snippet to change to superscript in MS Word and Pages
name: Superscript
icon: iconify:tabler:superscript
actions:
  - requiredApps: [com.microsoft.Word]
    keyCombo: command shift =
  - requiredApps: [com.apple.iWork.Pages]
    keyCombo: command control +