# 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. **Tip: Pressing a key from JavaScript** You can also use [`popclip.pressKey()`](https://www.popclip.app/dev/api/interfaces/PopClip.html#presskey) — or [`popclip.pressKeys()`](https://www.popclip.app/dev/api/interfaces/PopClip.html#presskeys), for a sequence of combos with optional waits — within a [JavaScript action](https://www.popclip.app/dev/js-actions.md). ## 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](#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). | ## 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. ```yaml #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: ` `, where: - `` is optional, and can be any combination of: | Modifier | Keyword | | -------------- | ----------------- | | Command (⌘) | `command`, `cmd` | | Option (⌥) | `option`, `opt` | | Control (⌃) | `control`, `ctrl` | | Shift (⇧) | `shift` | | Numeric Keypad | `numpad` | - `` 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`)** ```c /* * 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 ` 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: ```yaml #popclip name: Bold icon: B keyCombo: command b ``` Pressing a sequence of keys: ```yaml #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: ```yaml #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: ```yaml #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 + ```