How to make a Key Press extension in PopClip — TextExpander example

This is a guide to using the new extension snippets.
This post has been Updated on 3 May 2022 for PopClip 2022.5.

Once of the actions a PopClip extension can do is press a key combination for us.

As an example, I’m going to make a PopClip extension to create a new TextExpander Snippet (not to be confused with a PopClip extension snippet :upside_down_face:). (Long-time PopClip users may know there used to be a TextExpander extension, but it no longer works.)

I checked the TextExpander prefs and saw that it has a global keyboard shortcut for creating a snippet from the current clipboard. This is great, because we can make use of this for our PopClip extension.

First of all we need to go into the Hotkeys section of TextExpander preferences and set a keyboard shortcut for “Create Snippet from Clipboard”:

This can be any key combination of your choice, but here I’m using ⌃E (control and E).

Having done this, we can now make our PopClip extension. I’ve typed out an extension snippet as follows — all you need to do is go ahead and select it:

# popclip
name: TextExpander
icon: circle filled te
before: copy   # important line! see "the details" below
key combo: control E

CleanShot 2021-11-17 at 16.08.37

If you’ve chosen a different keyboard shortcut to ⌃E, you’ll need to type out the extension snippet yourself somewhere and alter it. Otherwise, after selecting the text block above with PopClip, you’ll see “Install Extension”.

Now you have an extension that creates a new TextExpander snippet from the selection!

CleanShot 2021-11-17 at 16.23.20

Hopefully you now have an idea how to adapt this for other situations where you can accomplish a task using a keyboard shortcut. Feel free to ask for help in the thread down below, or share things you have made.

The details :open_book:

Let’s look at the lines of the extension snippet in detail:

  • # popclip - this has to go at the top of every extension snippet so PopClip knows what it is.
  • name - the name you give the extension. You can choose any name you like.
  • icon - an icon for the extension’s action. Here I have specified a filled circle with the letters te but you can change that (see here for info)
  • before - this is important for the TextExpander extension. The before field specifies an action PopClip should perform before the main action. Here I have put copy which makes PopClip copy the selection to the clipboard, where TextExpander will find it.
  • key combo - the main action, which is to press a key combination. The key combo is specified as command E - see Specifying key combinations below.

Specifying key combos

The key combo is simply a sequence of words from command (⌘), option (⌥), shift (⇧) and control (⌃), followed by the character, name or key code of the key to press.

To specify more than one modifier, just list them separated with spaces, with the key to press at the end. The order does not matter. For example:

key combo: command shift =

key combo: option shift command W

key combo: control command space

PopClip recognises the following named keys: return , space , delete , escape , left , right , down , up , and the F keys: f1 to f19 .

Other more ‘esoteric’ keys can also be specified as a virtual key code in hexadecimal format.

Example:

#popclip example to press ⌘Tab
name: Copy, Switch App and Paste
icon: symbol:bolt.circle
before: copy
key combo: command tab
after: paste

Pressing a sequence of key combos

New in PopClip 2022.5, you can press a sequence of keys. This is done by specifying an array of key combos in key combos (with an ‘s’) field. Example:

#popclip snippet to press ⌘C twice
name: DeepL Translate
title: DeepL
key combos:
- command C
- command C

PopClip will pause for 1/10th of a second after pressing each key combo.


The full details about making extensions are in the technical documentation.

3 Likes

@nick many thanks for your work and also the detailed tutorial :+1:

I deviated a little from your solution because Textexpander has the default setting "Formatted text…) for me. Also, it bothers me that the TE display window is not centered on the desktop.

But thanks to Keyboard Maestro all this is no problem. So I don’t use the “key combo”, but the “url” solution.
After the TE window appears centered, the “Formatted Text…” setting is also changed to “Plain Text”.

2021_11_18_Support_1

1 Like

Thanks for the breakdown. Is there a way to add more than one keypress sequence.

like:

# popclip Hook 
name: Add Selection to Hook
icon: H
key combo: cmd shift space # Activates Hook
key combo: option q # Selects the Copy text and Link (Also adding to Hook)
1 Like

At the moment you can only specify one key press, although having the ability to specify a key press sequence may be a good enhancement :thinking:

However you can do it a bit more awkwardly with a JavaScript extension and the pressKey() method like this:

# popclip Hook 
name: Add Selection to Hook
icon: H
javascript: |
  popclip.pressKey(util.constant.KEY_SPACE, util.constant.MODIFIER_COMMAND|util.constant.MODIFIER_SHIFT)
  popclip.pressKey('Q', util.constant.MODIFIER_OPTION)

(I only have Hook lite version, and also I still don’t actually understand what Hook does yet :upside_down_face:, so I wasn’t able to test it properly…)

I’m hoping there will be some updates to hooks schema because even in testing with other applications I ran into some troubles with Hook myself. Still I can see the use-case of multiple keypresses or multiple steps.

I noticed in the hook menu there’s an item with shortcut control Q (rather than option Q) - is it possible that’s the problem?

No the issue I have is that often when I think this option should be available it isn’t which makes it hard to consistently trigger.

1 Like

I use an app called SideNotes. I want to be able to select text and then use an extension to create a note from the selected text only. This is my snippet:

# popclip
name: SideNotes
icon: sidebar.right
key combo: control option command N

This does what it is supposed to do, which is to create a new note in SideNotes. However, it doesn’t paste the selected text. Hence I added this line at the end:

key combo: control option command V

Now it says invalid YAML

Hence, I added another line, so that the new snippet looks like this:

# popclip
name: SideNotes
icon: sidebar.right
before: command C
key combo: control option command N 
key combo: control option command V

In lieu of command C, I have tried using just the word copy. What an I doing wrong?

Unfortunately it’s not possible to specify multiple Key Combo keys. (Though would be nice to add.)

You can do it different way though like this:

# popclip
name: SideNotes
icon: sidebar.right
before: copy
javascript: |
  popclip.pressKey('N', util.constant.MODIFIER_CONTROL | util.constant.MODIFIER_OPTION | util.constant.MODIFIER_COMMAND)
  popclip.pressKey('V', util.constant.MODIFIER_CONTROL | util.constant.MODIFIER_OPTION | util.constant.MODIFIER_COMMAND)

Edit: As of PopClip 2022.5, you can do it this way:

# popclip
name: SideNotes
icon: sidebar.right
before: copy
key combos:
- control option command N
- control option command V

The above script still doesn’t paste into the new note that is created. I just used what you’ve shown above.

Secondly, did you mean the keyboard shortcuts have to be just control and E that is two actions to did you mean TWO lines of Key Combo in the Extension Snippet?

Just that a snippet with a key combo: field can only have one such field. I’ll install SideNotes and see if I can have a look…

1 Like

I see control option command N creates new empty note by default … Maybe you need to set a shortcut for Note from Pasteboard?

1 Like

Yup, that did it. Here it is:

# popclip
name: SideNotes
icon: sidebar.right
before: copy
key combo: control option command V

Many thanks

1 Like

Re. SideNotes — we now have an officlal extension for this too: SideNotes — PopClip Extensions

1 Like